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This manual gives you conceptual information 
about using the 5110 with the APL language. 
Before using this manual, you should understand 
the information in the /BM 5770 APL Introduction, 
SA21-9301, especially: 


e How to enter data from the keyboard 


e How APL functions work with one or two 
arguments 


e How to create your own user-defined functions 
using the built-in APL functions 


This manual is intended to be used with the /BM 
5110 APL Reference Manual, SA21-9303; that is, 
this manual gives you information about using the 
5110 system with the APL language for 
information processing. The major topics are: 


e Computer concepts for data processsing 
(Chapter 1) 


e An approach to breaking your application into 
small parts to make programming easier 
(Chapter 2) 


e Elements of the APL language and example APL 
user-defined functions used for information 
processing (Chapter 3) 


e Controlling the information in the active 
workspace (Chapter 4) 


e Using uppercase and lowercase characters, 
scrolling the display screen up or down, and 
sounding the audible alarm (Chapter 5) 


e Creating, using, and maintaining your library 
(Chapter 6) 


e Using the tape or diskette storage media 
(Chapters 7 and 8) 
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e Formatting printed reports and example 
user-defined functions used for formatting 
reports (Chapter 9) 


e Creating and using data files for your business 
applications (Chapter 10) 


e Determining what to do when your program 
doesn’t work (Chapter 11) 


This manual is not intended to give you a 
complete description of the syntax and rules 
required for each APL command, function, or 
variable; you must use the 5770 APL Reference 
Manual for this information. 


This manual does not need to be read chapter by 
chapter. Instead, you can read the appropriate 
chapters as required. For example, you might read 
Chapter 9, Printer Contro/ when you need to 
format a report. 


This manual follows the convention that he means 
he or she. 


Prerequisite Publication 


IBM 5110 APL Introduction, SA21-9301 


Related Publications 
IBM 5110 APL Reference Manual, SA21-9303 
IBM 5110 APL Reference Card, GX21-9304 


!BM 5110 Customer Support Functions Reference 
Manual, SA21-9311 
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Chapter 1. Data Processing Concepts 


INTRODUCTION 


The IBM 5110 Models 1 and 2 are multipurpose data processing 
systems with a personal touch. Because of their compact size and 
large-scale capabilities, these systems provide solutions to problems 
for a wide variety of users. As a 5110 user, only you can determine 
the problems to be solved with your system. To help you make these 
determinations, this chapter contains general concepts of data 
processing. You may or may not choose to read this chapter, 
depending on your data processing knowledge and experience. 


CONCEPTS 


What can you expect a computer to do with information? How do you 
get information into a computer? How does a computer know what to 
do with your information? What final results can you expect from a 
computer? This section gives general answers to these questions. 


Today the computer is doing many jobs, from accounting to predicting 
election results to guiding spaceships. It is often looked upon as some 
kind of magical machine, but the computer performs no magic. 
Everything a computer does is dependent on the people who use it 
and the instructions they supply. For every job you want a computer 
to do, you must give a step-by-step procedure (a program) for it to 
follow. This procedure is then stored inside the computer. The 
information you want is processed according to the stored 
instructions. 


A computer can do only a few rather simple things, but it does them 
extremely well. It can retrieve, almost instantly, any item of 
information stored in it. It can compare any two items of information, 
and do any arithmetic Operations you want: add, subtract, multiply, or 
divide. It can be instructed to do any combination of these things in 
any sequence you want them done. 


The computer works methodically, doing one thing at a time. When it 
finishes one step, it goes on to the next, then the next, and the next, 
according to instructions. But it performs these steps at an almost 
unbelievable speed until it comes up with the answer you want. 
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The task performed by a computer is called data processing. Data 
processing means that information is handled according to a set of 
rules. Whether you process information by hand or use a computer, 
the requirements of a job remain about the same. You must have 
input, which is the data you want to do something with; you must 
process the data, which is the act of doing something with data 
according to instructions; and you must have output, which is the 
result of your processing. 


To help you understand the 5110 and data processing, let’s first look 
at how a clerk might process information for the job of billing. For this 
job, assume the clerk works with the following data: 

® Customer orders 

® Price catalogs 


® Customer records 


« Accounts receivable records 


Inventory files 


The clerk receives a copy of the customer orders after orders are 
shipped. He uses these documents to prepare bills that he sends to 
customers. To prepare the bill, he follows this procedure: 

1. Look up, in a price. catalog, the price of each item on the order. 
2. Multiply the price by the quantity shipped. 


3. Add the total price of items to get the total amount of bill. 


4. Check the customer records to see if any special discounts apply, 
and adjust the bills accordingly. 


5. Type the bill. 


6. Adjust the accounts-receivable records to show what the 
customer owes. 


7. Update the inventory records to show the reduced stock. 


For each billing, the clerk follows the same procedure. In computer 
terms, this procedure is his program for doing the job. The customer 
order is his /nput, the calculating and file updating he does is 
processing, and the results of the processing (the billing and updated 
records) are his output. 


The 5110 can speed up the billing operation and reduce costly errors. 
The order information can be entered from the keyboard; the records 
(such as price lists, customer records, accounts receivable records, 
and inventory files) can be quickly referenced and updated (processed) 
using tape or diskette storage; and the printer can print the billings. 
The parts of the 5110 used for data processing are: 

Input 


e The keyboard from which data is entered into the system. 


e Tape or diskette storage from which data can be read for 
processing. 


Processing 
e The 5110 internal storage, which includes the active workspace. The 


active workspace is where calculations are performed and where 
user-defined functions (programs) and variables are stored. 
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Output 


@ The display screen, which displays keyboard input and the results of 
executed expressions or statements. That is, the display screen is a 
means of communication between the system and you. 


e@ The printer, which prints keyboard input (if specified) and the results 
of executed expressions or statements. This printed output is 
sometimes called hard copy output. 


e@ The tape or diskette on which data can be stored for future 
processing. 


es Q 
GH 


As mentioned before, a program is a procedure or set of instructions 
you establish for doing a job. These instructions are necessary 
because a computer cannot think for itself. When defining a program 
for the 5110, you can use a programming language called APL. APL is 
a simple-to-use programming language with which you describe how 
you want the 5110 to do a job. Also, in APL, a program is called a 
user-defined function. 


The next chapter presents an approach to analyzing a problem or job 
so that an APL user-defined function can be used to help process 
information. 


Chapter 2. Information Processing 


This chapter presents an approach to dissecting an application so that 
APL user-defined functions can be used to help process the 
information. This approach helps you break down the application into 
manageable parts so that you can apply APL expressions and 
commands to process the information. Breaking the application down 
into manageable parts promotes thoroughness and allows the 
application to be solved (programmed) faster. 


INPUT, PROCESS, AND OUTPUT 
Every application consists of three parts: 
e The /nput required for processing. 
e The process (APL expressions) required to generate the final result 
@ The output, which is the final result 
Each part might consist of one or more APL expressions. In the 
following sections, each part is discussed in more detail. Also, an 


example for finding the compound interest is used to illustrate each 
part. 
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Output 
Because the output or result is the primary reason for a user-defined 
function to exist, considering the output provides the best place to 
start solving a problem. To do this, consider these questions: 
1. What results are required? 
2. How should the results be formatted? 
3. Who uses the results? For example, should the results be 

displayed or printed, or should the results be stored in the active 


workspace, on tape, or on diskette for later use? 


Now, for the compound interest example, assume the answers to 
these questions are: 


1. The amount of interest earned. 


2. The message THE INTEREST EARNED IS: followed by the 
calculated interest earned. 


3. Finance officers will use the displayed results to evaluate 
different plans. 


Once you have answered these questions, you know the purpose of a 
user-defined function. 


Input 


After the output, you should consider what input data is required to 
generate the output. To do this, consider such questions as: 


1. What input is required? 
2. Where does the input come from? 
3. How is the input provided? 


Continuing with the compound interest example, the answers to these 
questions are: 


ath The interest rate, number of years, and principal. 


2. From finance officers who need to know the amount of interest 
earned for different plans. 


3. Through the 5110 keyboard. 


In our example, most of the input data will come from the keyboard; 
however, other ways also exist. For example, some data might be 
permanent and be included within the user-defined function (for 
example, headings and labels). There might also be data that is usually 
constant but, for certain problems, must be changed. This data might 
be coded in the user-defined functions as variables that can be 
modified. And, of course, data might also be from tape or diskette. 


The following list summarizes the input and output considerations so 


far: 
Data Device 
Input Interest: rate | Keyboard 
Number of years 
Principal 
Output THE INTEREST EARNED IS: Display Screen 


The calculated interest earned 
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Process 
Your introduction to APL started with APL’s processing ability. The 
APL language is designed to do processing with a minimum number of 


instructions. 


Once the input and output are well defined, all of the characteristics 
work together to make the process part the most straightforward. 


For our compound interest example, the process part consists of: 
1. Defining the algorithm used to calculate the compound interest 
2. Using the input to generate the results | 
The formula used in this example for the compound interest is: 

Cl = Principal x (1 + .01 x Interest Rate)ye2s 


The APL statements that use the input to generate the results might 
be as follows: 


Aéil+, OL xeINTERESTRATE 
BEAXYEARS 
Ce PRINCTPAL»«& 


PUTTING IT ALL TOGETHER 


Now that you have considered the three parts of the application, it is 
time to write your user-defined function. For the compound interest 
example, your user-defined function might look like this: 


The interest rate must be 


YO RePRINCTPAL COMPOUND YEARS assigned to this variable before 


ie ae A@L+0, GLX INTERESTRATE eae 
: : ; spear ita eee the user-defined function is 
cao CLE PRINCIPAL ®E executed. 
oe Re ' THE INTEREST EARNED IS: °, 410 2 #C2 

¥ 


So far, you have taken a simple application and designed a 
user-defined function to solve it. If the application is larger or more 
complex, a more detailed structure is required. This more detailed 
structure involves expanding each of the three parts (input, process, 
and output) into additional levels of input, process, and output. 


ADDITIONAL LEVELS OF INPUT, PROCESS, AND OUTPUT 


User-Defined 
Function 


PROCESS 


First Level 


OUTPUT 


Additional Levels 


. 


The method shown in the previous diagram breaks the first-level 
INPUT, part into manageable parts. Let’s continue with the compound 
interest problem and treat the INPUT portion as a separate problem in 
itself. 


First, consider the output of the INPUT portion. Here the output is 
actually the input for the first-level PROCESS portion. In this case, 
assume that the output must be an interest rate not greater than 18%, 
a number of years not greater than 40, and a principal not greater than 
500000.00. 


Next, consider the input for the INPUT portion. The input is the same 
as before (the interest rate, number of years, and principal for which 
the interest earned must be calculated). However, in this case, the 
finance officers might be unfamiliar with the user-defined function; 
therefore, there should be prompting messages telling them what to 
enter. 


Finally, consider the process for the INPUT portion. In this case, the 
processing consists of error checking and validation of ail the input 
data, because you want to make sure that the interest rate is not 
greater than 18%, the number of years is not greater than 40, and the 
principal is not greater than 500000.00 
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Now, taking these considerations into account, the APL statements for 
the first-level input portion might be: 


YO REE XAMPLE 


Li STARTICE 


C2 X&[] 


NYTER THE INTEREST RATE, YEARS, ANID PRINCIPAL 


13 SCCXCL 7218), OXC27540), OX03725900000))/E1,82,E83 


ry 4PROCES 


Lal: E2s “THE 
C41 +S TART 
C7] E22: THE 
I 3 oI ASTART 
COT ES. THE 
Lid] +START 
C219 PROCESS: 
V 


5 
INTEREST RATE IS GREATER THAN 18 PERCENT’ 


NUMBER OF YEARS IS GREATER THAN 40° 


PRINCIPAL IS GREATER THAN SO00000.00° 


As you break an application down into more manageable parts, you 
might want to have a separate user-defined function for each part. For 
example: 


¥o Re INTEREST ~ 
‘| Re INPUT 
27 RePROCESS R 
‘| ReQUTPUT R 


Vo Xe INPUT 
Pia STARTS CENTER THE INTEREST RATE, YEARS, ANID PRINCIPAL 
Cec Xe[] 
ral POCKEA TS 1B), CXL 2040), XLS SO0000 SEL, E2,E3 
ho +0 
Cod EL: ' THE INTEREST RATE IS GREATER THAN 18 PERCENT’ 
Céc ASTART 
CY Et THE NUMBER OF YEARS IS GREATER THAN 40° 
CSc SS TART 
CO) ES: THE PRINCIPAL IS GREATER THAN 500000,00° 
CiQd ASTART 
V 


¥ CLePROCESS INPUT; A; & 
Ca AfL+0. 0. INPUTEL 
ae ReAXINPUTE 23 
3c CLeQINPUTE SI «8 


Vo R¢EQUTPUT CT 
es ae Re THE INTEREST EARNED IS: ', 10 2 +C1 
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CONCLUSION 


When programming for an application using the 5110, break the 
application down into manageable parts. To do this, first focus on the 
program output. This is the primary interface to the user. It also 
defines what the real purpose of the program is. Next, consider all the 
input data that is required to generate the output. Finally (and only 
then) plan the actual processing. 


Thinking in this way should help you make the transition from knowing 
the APL language to being able to use the APL language to generate 
user-defined functions for specific applications. 


Chapter 3. APL Language Elements 


In this chapter, the following topics concerning the APL language 
elements are discussed: 


e Variables 
e Data representation 
e Arrays 


e@ Examples of useful APL statements and user-defined functions 


VARIABLES 


You can store data in the 5110 by assigning it to a variable name. 

‘These stored items are called variables. Whenever the variable name 
is used, APL supplies the data associated with that name. A variable 
name can be up to 77 characters in length with no blanks; the first 
character must be alphabetic, and the remaining characters can be any 
combination of alphabetic, and numeric characters. The « (assignment 
arrow) is used to assign data to a variable: 


LENGTHES 
WIOTHES 
ARE A¢LENGTHxWITTH 
To display the value of a variable, enter the variable name: 
LENGTH 
WILOoTH 


AREA 
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DATA REPRESENTATION 


Numbers 


The decimal digits 0 through 9 and the decimal point are used in the 
usual way. The character , called the negative sign, is used to denote 
negative numbers. It appears as the leftmost character in the 
representation of any number whose value is less than zero: 


The negative sign, _, is distinct from - (the symbol used to denote 
subtraction) and can be used only as part of the numeric constant. 


Scaled Representation (Scientific Notation) 


You can represent numbers by stating a value in some convenient 
range, then multiplying it by the appropriate power of 10. This type of 
notation is called scaled representation in APL. The form of a scaled 
number is a number (multiplier) followed by E and then an integer (the 
scale) representing the appropriate power of 10. For example: 


Number Scaled Form 
Multiplier 
66700 6.67E4 
Scale 
00284 2.84E 3 


The E (E can be read times 10 to the) in the middle indicates that this 
is scaled form; the digits to the right of the E indicate the number of 
places that the decimal point must be shifted. There can be no spaces 
between the E and the numbers on either side of it. 


Numeric Value Range 
Numeric values in the 5110 can range from — 7.237005577332262E75 
to 7.237005577332262E75. The smallest numeric value the 5110 can 
use is +5.397604346934028E 79. 

Numeric Value Precision 


Numbers in the 5110 are carried internally with a precision of 16 
significant digits. 


Character Constants 


Zero or more characters enclosed in single quotes, including 
overstruck characters and blank characters (spaces), is a character 
constant. The quotes indicate that the characters keyed do not 
represent numbers, variable names, or functions, but represent only 
themselves. When character constants are displayed, the enclosing 
quotes are not shown: 


"ARCTIERG ' 
ABCTIEFG 
"L23A6RC' 
123ARC 
Me’ THE ANSWER IS: ' 
M . 


THE ANSWER IS: 


When a quote is required within the character constant, a pair of 
quotes must be entered to produce the single quote in the character 
constant. For example: 


‘NON’ ' T GIVE THE ANSWER AWAY ' 
QON'T GIVE THE ANSWER AWAY 


Logical Data 


Logical (Boolean) data consists of only ones and zeros. The relational 
function (> 2 = < < +) generate logical data as their result; the result 
is 1 if the condition was true and 0 if the condition was false. The 
output can then be used as arguments to the logical functions 

(A v » % & ) to check for certain conditions being true or false. 
Logical data can also be used with the arithmetic functions, in which 
case it is treated as numeric 1’s and 0's. 
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ARRAYS 


Array is the general term for a collection of data, and includes scalars 
(single data items), vectors (strings of data), matrices (tables of data), 
and arrays of higher dimensions (multiple tables). All primitive (built-in) 
functions are designed to handle arrays. Some functions are designed 
specifically to handle arrays rather than scalars. Indexing, for example, 
can select certain elements from an array for processing. 


One of the simplest kinds of arrays, the vector, has only one 
dimension: it can be thought of as a collection of elements arranged 
along a horizontal line. The numbers that indicate the positions of 
elements in an array are called indices. An element can be selected 
from a vector by a single index because a vector has only one 
dirnension. The following example shows assigning a numeric and a 
character vector to two variable names, N and C; the names are then 
entered to display the values they represent: 


Ne% 6.2 "3 888 95.12 
N 
& 4,2 "3 888 95.12 
(Ce ABCTERG" 
C: 
ARCTERFG 


Generating Arrays 


The most common way to generate an array is to specify the shape 
the array is to have (that is, the length of each coordinate) and the 
values of the elements of the new array. The APL function that forms 
an array is the reshape function. The symbol for the reshape function 
is p. The format of the function used to generate an array is XpY, 
where X is the shape of the array and Y represents the values for the 
elements of the array. For the left argument (X), you enter a number 
for each coordinate to be generated; this number indicates the length 
of the coordinate. Each number in the left argument must be 
separated by at least one blank. The values of the elements of the 
new array are whatever you enter as the right argument (Y). The 
instruction 7pA means that the array to be generated has one 

_ dimension (is a vector) seven elements in length, and that seven 
values are to be supplied from whatever values are found stored under 
the name A. It does not matter how many elements A has, as long as 
it has at least one element. If A has fewer than seven elements, its 
elements are repeated as often as needed to provide seven entries in 
the new vector. If A has more than seven elements, the first seven 
are used. The following examples show generation of some vectors: 


7 f 1 2 3 
ns Che 
j 


«6 12.3 
2PLes 

125 123 
weil. a 


tad hed: Aa @. Ve deed 
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An array with two coordinates (rows and columns) is called a matrix. 


Columns 


9 10 11 12 


To generate a matrix, you specify X (left argument) as two numbers, 
which are the lengths of the two coordinates. The first number in X is 
the length of the first coordinate, or number of rows, and the second 
number is the length of the second coordinate, or number of columns. 
The following example shows how a matrix is generated: 


M¢e2 Sal 2 3 US } 
M 


. 
CH Po 
cs i 


Me? Ue ARCTIEFPGH ' 


M 

ABCTI 

EF GH 
Mil¢2 Sem 
Mi 

ARC 

NEF 


Note that the values in the right argument are arranged in row order in 
the arrays. If the right argument has more than one row, the elements 
are taken from the right argument in row order. 


The rank of an array is the number of coordinates it has, or the 
number of indices required to locate any element within that array. 
Scalars are rank 0. Vectors have a rank of 1, matrices have a rank of 
2, and N-rank arrays have a rank from 3 to 63 (where N is equal to the 
rank). N-rank arrays, like matrices, are generated by providing as the 
left argument a number indicating the length for each coordinate (for 
example, planes, rows, and columns). The following examples show 
how to generate 3-rank arrays. Note that the elements taken from the 
right argument are arranged in row order: 


ARCH 
EP GH 
CK LL 


MNOP 
GIRS T 
UVWX 


A&  ABCTERGHIT UIKLMNOPOGRSTUVUXYZ ' 
eo le pA 


2-Plane, 3-Row, 4-Column Array 


Y 3 2A 


4-Plane, 3-Row, 2-Column Array 
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Finding the Shape and Rank of An Array 


Once you have generated an array, you can find its shape (number of 
elements in each coordinate) by specifying p (shape function) with 
only a right argument, which is the name of the array. If A is a vector 
with six elements and you enter pA, the result is one number because 
A is a one-dimensional array. The number is 6, the length (number of 
elements) of A. The result of the shape function is always a vector: 
ACL 222 333 Yb SSS 4646 
en 
& 


The shape of a matrix or N-rank array is found the same way: 


M¢2? Sol 2? 3 US 6 
M 

i 2 3 

LS 4 
eM 


Re? Sued 234 S&S 6& 7 8B 
R 
tL 23 4 
a 6 7 8 
2 3 YU 


aw & 7 8 
123 4 
uw & # 8 

er 


) 
oi 


ty. 


In some cases, it might be necessary to know just the rank, the 
number or coordinates (or indices) of an array. To find the rank, enter 
o 9 (shape of the shape) and a right argument, which is the name of . 
the array: 


ALI 222 333 Yul SOS 646 
hee? Sel 2 38 WG 6 
Ce? S upl 234 5 6 7 


pA 
é 

PPR 
A 

ok 
2 0 

Pek 

ec 
2 3 4 

pel 
3 


The following table shows what the shapes and ranks are for the 
various types of arrays: 


Data 
Type Shape p X . Rank ppX 
Scalar No dimension (indicated 
by an empty vector). 0 
Vector Number of elements. 1 
Matrix Number of rows and the 
number of columns. 2 
N-rank Each number is the length 
arrays of a coordinate. N 


Empty Arrays 


Although most arrays have one or more elements, arrays with no 
elements also exist. An array with no elements is called an empty 
array. Empty arrays are useful when you are creating lists (see 
Catenation in this chapter) or branching in a user-defined function. 


Following are some ways to generate empty arrays: 

e Assign 10 to a variable name to generate an empty vector: 
EVECTORE 10 
E VECTOR An empty array is indicated 


by a blank display. 
PEVECTOR y play 


0. | The shape of the empty vector 


is zero (zero elements). 


e Use a zero length coordinate when generating a multidimensional 
array: 


This matrix has three rows and no (0) 
EMATRIXL©3 O10 columns. If one of the coordinates is 
EMATRIX1 not zero, you cannot generate the 
empty array. 


PEMATRIXA 
A Blank Output Display 


e A function might generate an empty vector as its result; for 
example, finding the shape of a scalar: 


pA 
A Blank Output display. 
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INDEXING ARRAYS 


You may not want to refer to the whole array but just to certain 
elements. Referring to only certain elements is called indexing. Index 
numbers must be integers; they are enclosed in brackets and written 
after the name of the variable to which they apply. Assume that A is 
assigned a vector as follows: A <« 11 12 13 14 15 16 17. The result of 
entering A is the whole vector, and the result of entering A[2] is 12 
(assuming the index origin is 1). 


Here are some more examples of indexing: 


Ae&Li 12 13 14 15 16 1? 


ALS 
13 
Abs % ¥ ai 
15 13 17 it 
Res 1 4 & Blank Character 
AUER 


13 11 14 164 

Re ABCTIEFGHT JIKLMNOPQRS TUVWXYZ 

ROW Lode 24 1 44 & 2 3 12 1 9 Led 
AN ANT CLAIR 

(eee 9 la YF ik F fT 

BEC 
VIRGINIA 


If you use an index that refers to an element that does not exist in the 
array, the instruction cannot be executed and INDEX ERROR results: 


a) 

Tt 42 43 14 15 14 17 
ALB" 

INTEX ERROR 
AL 8 2 


A 


You cannot index or do anything else with an array until after the array 
has been specified. For example, suppose that no value has been 
assigned to the name Z; then an attempt to store values in certain 
elements within Z would result in an error, because those elements do 
not exist: 


203 UIELS US 
VALUE ERROR 

£035 le 13 4S 

tA 


Indices (whatever is inside the brackets) can be expressions, provided 
that when those expressions are finally evaluated, the results are 
values that represent valid indices for the array: 


B 
ARCKEF GHIIKLMNOPQRS TUVWXYZ 
X¢e1 23 4 3 
BEXx23 
BOFHA 
x 
12 34 9 
BL L+X« 37 
GIMP 


The array from which elements are selected does not have to be a 
variable. For example,.a vector can be indexed as follows: 


235 5 7 9 dl ig 1S 17 igh? 24 2a 
13 3 7 3 
“ABCTEFGHIJIKLMNOPQRSTUVWXYZ ‘(C12 15 15 11 27 16 124 
LOOK PA 
"ABCKEFGHIUIKLMNOPQRSTUVWXYZ (£2 “el 1S 14 27% 13 1°18 257 
NON 
MARY 


Indexing a matrix or N-rank array requires an index number for each 
coordinate. The index numbers for each coordinate are separated by 
semicolons. Suppose M is a 3 by 4 matrix of consecutive integers: 


Me Wert? 


If you ask to see the values of M, they are displayed in the usual 
matrix form: 


M 
1 2 3 4& 
32 © ¢f 8B 
? 10 11 12 


If you want to refer to the element in row 2, column 3, you enter: 


ME; ao 


7 
If you want to refer to the third and fourth elements in that row, you 
enter: 
Mie; 4 
7 8 
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Similarly, to refer to the elements in column 4, rows 1, 2, and 1, you 
enter: 


MEd 2 Lea 
YU 


You can use the same procedure to select a matrix within a matrix. If 
you want the matrix of those elements in rows 2 and 3 and columns 1, 


2, and 1 of M, you enter: 


ee 


=z 
ri 
BS 
a 

in 
we 


SS oS 

9 Lo °° 
If you do not specify the index number for one or more of the 
coordinates of the array that you are indexing, APL assumes that you 


want the entire coordinate(s). For instance, to get all of row 2, you 
enter: 


M25 J 
a4 7% & 


Or to get all of columns 4 and 1, you enter: 


MOG 12 
Od 
Ss re 
ie 


Note: You still have to enter the semicolon to make clear which 
coordinate is which. The number of semicolons required is the rank of 
the array minus one. If the correct number of semicolons is not 
specified, RANK ERROR results: 


Mes Werle 
pM 
3 
MI 4 19 
RANK ERROR 
MIG 16? 
A 


You can change elements within an array by assigning new values for 
the indexed elements. (The rest of the array remains unchanged.) 


Ae3 Sel 23 4 & 6 7 8 YP 


A 
1 2 3 
Y 4 4 
{3 9 
ACS) 2 S4¢10 20 
Pe 
iL 2 3 
HW 10 20 
Pf 8 & 


JOINING ARRAYS TOGETHER 


You can join two arrays to make a single array by using the catenation 
or lamination functions. The symbol for these functions is the comma. 


Catenation 


When catenating vectors, or scalars and vectors, the variables are 


joined in 


be Ss 


ie: 


the order in which they are specified. For example: 
Ae] 2 3 
Rely 3 4 
A, & 

Ss a ee 
BUA 

6 12 3 4 
A, 2 

3 ly. 2 
3,8 

2 oS OM 


When catenating two matrices or N-rank arrays, the function can take 


the form 


A,[I]B, where | defines the coordinate that will be expanded 


when A and B are joined. If the coordinate is not specified, the last 
coordinate is used. When A and B are matrices and [I] is [1], the first 
coordinate (number of rows) is expanded; when [I] is [2], the last 
coordinate (number of columns) is expanded. The following examples 
show how to catenate matrices: 


| Graphic Representation 
A B 
Aen Sel0 20 30 40 SO 40 10 20 30 11 22 33 
Ree Seld 22 33 Wl SS 46 40 50 60 44 55 66 


20 30 11 
20 40 WY 


A, E28 
20 40 11 
YO 60 Wu 


A, C18 
20 30 


DU 60 
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Arrays of unequal sizes can be catenated, provided that the lengths of 
the coordinates not specified are the same (see the first example 
following). If the coordinates not specified have different values, an 
error results (see the second example following): 


Ae? Zol0 20 30 40 50 460-—+|40 
Re? Well 22 33 44 55 66 77 88 


A, C218 A 
10 20 30 11 22 33 Wy———__-|10 20 30 11 22 3344 
40 50 60 55 66 77 88 40__50 60 55 66 77 88 
A 0 20 30 Y 
A, CLIB 40 50 60 Yy 
1 RUGS TLR RR (9 YY, 
O,C19 & B 11 22 33 44] 
aA 


55 66 77 88 


A scalar can also be catenated to an array. In the following example, a 
scalar is catenated to a matrix. Notice that the scalar is repeated to 
complete the coordinate: 


A #2 $o10 20 30 40 SO 40 


16 20 30 
HO 30 40 
A, C2199 
10 20 30 99 
WO 50 460 99 
A, CLASS 
10 20 30 
HO SO 40 
99 OO 29 


A vector can also be catenated to another array, provided the length 
of the vector matches the length of the coordinate not specified. See 
the following examples: 


i preg: 00 110 | 20 | 30] 99] 
10 20 30 99 
LO 30 60 88 ae [0] 60] 88 
A, C1199 98 110 | 20 | 30] 
LENGTH ERROR 40 | 50 | 60] 
A, C11 99 88 oo fas GF 
“A 


The catenate function is useful when you are creating lists of 
information. Sometimes it is necessary to use an empty array to start 
a list. For example, suppose you want to create a matrix named 


PHONE where each row will represent a seven-digit telephone number. 


First you want to establish the matrix, then add the telephone numbers 
at a later time. The following instruction will establish an empty array 
named PHONE with no (0) rows and seven columns: 


PHONE® 0 %e.d 
PHONE. Blank display indicates an 


empty array. 


Pe PHONE 


Now, the telephone numbers can be added as follows: 


PHONE PHONE, CID 5336686 ° 
PHONE 

2336684 
PHONEPHONE, CLD Sale ee ' 
PHONE 

Wo dGO4 

WOM EL 


PPHONE 
aes 


\ The list of telephone numbers 


now contains two rows. 
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Lamination 


When laminating two variables together, the function joins the 
variables together by creating a new coordinate. The function takes 
the form A,[I]B, where | is an index number that must be a fraction. 
This index number specifies where the new coordinate is added. If the 
index number is less than 1, the new coordinate is added before the 
first coordinate; if the index number is between 1 and 2, the new 
coordinate is added between the first and second coordinate; and so 
on. For example: 


Graphic Representation 


AtZ Bota’ 
A 
AAA 
AAA 
AAA | 
HES Belk 8 |B |B | 
K BI B/B| 
BRR B/BiB. 
BEE 
KBR 
Cea, 0. LE 
Cc 
AAA 
AAA 
AAA 
BRE 


BRE The new coordinate is added before 
BRE no first coordinate. 

eC 
2 3: 3 


Cea, C1, 118 


AAA 
REE 


AAA 
BEE 


AAA 

REE 

a eC The new coordinate is added between the 
ee ae Se first and second coordinate. 


Cea, 2.108 
(’ 


232 4 The new coordinate is added after the 
second coordinate. 
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The new coordinate is always 2 because two variables are joined 
along a new coordinate. 


Unless one of the variables is a scalar, arrays of unequal sizes cannot 
be laminated together. For example: 


AtS Sar. 
A 

tL 2 3 

eo 

78 9 
Cea, 0, LI10 
C 


Be? Se10 11 12 13 14 15 


10 141 12 Folia} 21 
13 14 15 alia 
B,C. LIA 
LENGTH ERROR 
B,CO.11 A 


Aw 


USEFUL APL STATEMENTS AND USER-DEFINED FUNCTIONS 


To remove duplicate blanks from a character vector: 


VCOMPRESSUQIV 
¥ ZECOMPRESS Wil 
ie ZELECCIOT OAT EeW=" OO /sWE* OW 


COMPRESS "AAA 
AAA BEBE COC DN 


REBE CC QE 


The right argument is the character vector. 


To create a matrix from a character vector with a delimiter for each 
row: 


VEORMEINIY ee 10 will be set to 0 just during 
V MEL FORM SIAL BRIX: ZITO the execution of this function. 

ria Wxrd¢o | 

red Me ¢X¢ S01) /S¢,S 

3c ZECXHLIEX, #1 tXd/ 11 ax 

ru Me CC pA), Boe, (And) ©, fee orp /Aexle-11/2-0, “14 ZN 


y 
‘e' FORM ‘AskeCOCet 

A 

BR 

Coe In this example, the « character is used © 

‘f as the delimiter. The left argument specifies 


the delimiter, and the right argument | 
specifies the character vector. 
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To remove the alphabetic characters from a character vector, leaving 
only the numeric characters and blanks: 


VREMOVELT IY 
VO ONEW¢REMOVE OLD 
ee ie NEW COLME  O1L25456789. 'O OLD 
V 


Ole 'TAN 30 TAVE 29,35 JERRY 37 MEL 40,8" 
REMOVE OLD 
30 29.5 87 440.8 
To replace all trailing blanks with a minus sign: 
VBLANKSEGAY 
¥VoZe BLANKS M)V 

a a Ve, DaydM=' ' 

2d Ze, M 

Cac ZUV/ i eVile tH! 

iY 3 Ze COM) pz 


MAT¢2 Se' Ab CoH 
MAT 

Ak 

CHE 
RLANKS MAT 

COE ~~ 


Return all elements of a vector that are even numbers: 


VEVENDTAV 
¥V Z¢EVEN V 
oe ZEeCO@2IVI/V 
¥ 


EVEN 0 1 2 34 3 6 7 8 Y 
Meu és 


To delete all comment lines from a user-defined function: 


VCOMMENTIOAV 
¥o COMMENT FNM 
rid Mee XCME | LI4 al O¢MELICR FN 
V 


VAM 
Lid aCOMMENT LINE 1 
Can a 
PS aCOMMENT LINE 2 
Doe OV 


COMMENT ‘AD 
VADIIC GAY 
VAL 
Ca Sty 
¥ 


To merge two variables with the same shape into a single vector: 


VMERGECQIY 
¥ Z¢A MERGE & 


ae Z£¢,A,C0I0-0.51 & 


Ae 2a A! 
Bee Be’ 


A MERGE & 
AAAABRBE 
To delete duplicate elements in a vector: 
VOUPLICATERMIY 
¥Y Z¢eQnuPLICaATe Vv 
TA Ze CCrpPVIEViVo/VeE,V 
¥ 


QUPLICATIE 1 
1234 3 4 


28 3 4 235 6 


wow 


To find the first nonblank character in a character vector: 


VNONBLANK CTV 
¥oZe¢NONBLANK W 
ZeltcWe#' "OS 


Ve DAN’ 


NONELANK ¥V 
if) 

VNONBLANKXETTIV 
VoZeNONBLANKX W 


Co Ze CiNWe? S/W 
V 
NONBLANKX V 
qi 
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To determine whether a variable is character or numeric: 


a 


N 


VOETERMINED LIV 
QETERMINE W 
"NOC EETOH CTL tetlt Woe CY 


Ae 9! 
Wey 
QETERMINE A 


CETERMINE 2 N for numeric. 


VOE TERMINED COAV 
DETERMINED W 
“NCCRWTO+ C= at 0 ew 
QETERMINED A 
DETERMINED & 


To make scalar or vector into a matrix: 


¥ 
ie 
V 


VMATRIXETAV 
ZeMATRIX 
Ze CT STL, 1, eM eM 


Ae ARCTEFG " 
X& MATRIX A 
x 


ARCIEFG 


LY of 


ox The result is a 1 by 7 matrix. 


To delete all user-defined function names starting with a specified 
character vector from the active workspace: 


y 


VALUE 


VOELETERPNE TAY 
QELETEPN CONLS 25x 


Ze CCCCLPeNLD, ePCOTNL A, BC]  COANLE CIT TO) TNL 


Xe [TEX Z 


VADon ga ¥ 


Atit A user-defined function in the 


cor active workspace 


DELETERN "ATI 


ALK 
E RROR The function is no longer in the 


ATT . active workspace 
“A 


The result is C for character or 


3 


To count the number of occurrences of each unique character in a 
character vector: 
YCOUNTELIAY 
¥ ZeCOUNT WUC 
C13 ZeeeyWe , = CTAVEW) ¥TAV 
v 
COUNT 'ABBCCCITONE ' 
L234 
COUNT ‘ABCTIBCHCIN 


To center the character string in each row of a character matrix: 
YCENTERE CIV 
Y ZéEeCENTER M 
n47) Le CHP CeSANOME' DED OME CHE /SANME' OOM 


v 
MAT¢S 6e'° A B C 
MAT 
A 
i 
C" 
CENTER MAT 
A 
i 
C 


To right-justify the character string in each row of a character matrix: 
VRIGHTIUSTIFYR OAV 
Vo Z¢RIGHTIUSTIFY 
C4 Le Cm t SAN COM) OM 


y 
MAT 
A 
i 
C 
RIGHTIUSTIFY MAT 
A 
i 
( 
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LISTFNSCI3)] —_—————————_ 


To left-justify the character string in each row of a character matrix: 
¥VLEF TJUSTIFYCUQAY 


¥ ZeLEFTJIUSTIFY 
43 ZeC+/arnh=' * OM 


MAT 


LEFTJUSTIFY MAT 
13 
C° 
To list each user-defined function in the active workspace: 


VLISTFNSCTAYV 


VO LISTFNS ALF NAME; TS FUN; COL NO DTO; PW 


ATHIS FUNCTION LISTS ALL FUNCTIONS IN THE ACTIVE WORKSPACE 
aE XCEPT LISTENS ANT LISTVARS., | 
WiO0ed 

LIPWe 132 

NAME IINE 3 

ALFe' ABRCTEFGHTIKLMNOPGRS TUVWXYZ ' 

ALFCALF, ‘ AABCUEFGHLIKLMNGPQRSTUVUXY ZA ' 

ALFe ALF,  OL2SNSS7RS’ 

NANECNAMET AGS. ALF UaNAME 5 

Teg 

LOOP LAC CL teNAME ele T4+19/0 

+CA/NAMEL DS I= C7 it eNAME tT ' LISTFNS ' O/LOOP 
2CA/NAMELTS Te C71 tf eNAMED Tt LISTVARS 5D /LOOP 
NOeLteF UNE TICR NAME TS 7 

COLE CONG, de T'D, CF ONO, Le Le rWNO), COND, 2p Df) 
COLE L Je cvTiteloOlot' 

COL, FUN 

A Se > aka 

+LOOP 


LISTENS 

Ze BLANKS M;)V 
Ye  DANDMe! 
Ze, M 
ZEV/ eV Tel 
Ze C pM) pZ 


Zea BY BS ROW 

At C2T CePA, 1 La pA 

The ATTN key was pressed before 
all the functions in the active 
workspace were listed. 


To list each variable and associated value in the active workspace: 


YLISTVARS EO AY 

¥V LISTVARS ALP VAR; TC; RTO 
Ri  afHIS FUNCTION LL a THE VARATBLES TN THE ACTIVE WORKSPACE, 
(2c NtOe d 
C32] ReLteVARelTNL 2 
uy ALF e * ABCTIEF GH TJKLMNOPGRS TUVWXYZA 
v3] ALFEe ALF,  ABCTEFGHT JKLMNOPGRS TUVWXYZA' 
Dé ALF e AL e; ‘OLS SUB 6789 * 
eo VAREVARLAS6 LALF VEVAR: J 


3 2 Teo 

09 3 LOOP. 3CR« Te T+1970 
Rid] 2 1 pp 

Rid ale! ‘ VARET So 
Ried 38LOOP 


V 


LISTVARS 


A 
10 20 30 
HO SO 40 


kk 
Li 22 33 
WH SS 6G 


The ATTN key was pressed before 
Cc all the variables in the active 
AAA workspace were listed. 
i 


LISTVARSE L274 
To field-protect high-order digits: 
YPROTCOAY 
Vo ZeN PROT V 


Cao LeCmNIT COINS) oO LV 
¥ 


10 PROT ‘'123,45' 
HHEMLLS US 
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To delete leading blanks from a character string: 


POLEED AY 
7 Zee A 
Ci ZecU1e Ch=' SAGA 
? 


DLE ¢ 1235 4S" 
123 45 


To join vectors and print results as a single, sorted vector: 


VIOUNE DAY 
Vi ZeA JOIN BST 
m4 ZeTlaT¢ea, Bo 
¥ 


Bel & 227 


A JOIN B 
Loe Se 2S eS 6 OT A TS 


VIOTNICII¥ 
¥ ZeA JOTNI BOT 
C4] ZeTOUPTCA, BI 


A JOINT & 
15 10 74355 3 22 21 


To sort up to the first nine columns of a matrix with each row 
representing a name: 
VSORTOUAY 
VoOo2e SORT LIST: ALE 


ee ALPE" ABCOEPGHTUIELMNOPGRS TUVIS ¥2 ° 


v 


ARCHTE 

NOUGLAS 

BETH 
L¢SORT LL, 
ls 


ARCHTE 
BETH 
TOUGLAS 
WAN 
HENNY 
LUCY 


To find the location of a name in a list of names: 
VR UINOEITY 


Vo ZeLIsT FING NAME 
13 Ze CCLISTA. 2 CTL tel IST) tNAME DD 4 ul teLIs4y 


lL FIND * JAN? 


To delete a name from a list of names: 


VORLUT AY 
Yo 2eLIST DEL NAME 
nad Ze €CeLiStTa, eC tel IST) tNAME DO ALIST 


Ww HEL. ' ANS 
ARCHTE 

BETH 

QNOUGLAS 

JENN Y 

LUCY 
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To perform a specified operation if a condition is true: 


VIF COV¥ 
Yo Z2e0OP TF CONT 
4 Z2¢COND/OP 


Tes 
"PRINTS TF [=3 


PRINT 
"PRINTS TI Tost 


Chapter 4. Active Workspace Control 


The active workspace is the internal storage where calculations are 
performed; it is also the place where variables and user-defined 
functions are stored. The 5110 system commands, system functions, 
and system variables are used to control the active workspace. In this 
chapter, the following topics are discussed: 


@ The active workspace environment in a CLEAR WS 
e Getting information about the active workspace 


e Changing the active workspace environment 


Getting data into the active workspace 


e Active workspace storage considerations 
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THE ACTIVE WORKSPACE ENVIRONMENT IN A CLEAR WS 


When the 5110 is first turned on, or the RESTART switch is pressed, 


- or the )CLEAR command is executed, the active workspace 


environment has the following characteristics: 


The index origin (DIO) is 1. 


The comparison tolerance (ICT) is 1E-13. 


The random number seed (ORL) is 16807. 


e The print width (OPW) is 64. 

e The print precision (OPP) is 5. 

e The latent expression (OLX) is an empty vector. 

@ The workspace identification [ )WSID ] is CLEAR WS. 
@ The number of symbols allowed [ )SYMBOLS ] is 125. 


(See the /BM 5170 APL Reference Manual, SA21-9303, for a complete 
description of the system variables and system commands.) 


These characteristics control the way some of the APL functions and 
system commands will work in the active workspace. For example, if 
you have assigned 125 variable names and you enter the statement: 


NAME L246¢ ROCHESTER ' 
SYMBOL TABLE FULL 
MAME L246 


“a 


a SYMBOL TABLE FULL error message is displayed, because only 125 
symbols (names) are initially allowed in the active workspace. How 
you change some of the active workspace environmental 
characteristics is discussed next. 


CHANGING THE ACTIVE WORKSPACE ENVIRONMENT 


You can change the system variables, workspace identification 
[ )WSID ], and number of symbols allowed [ )SYMBOLS ]. For the 
system variables, you simply assign them a new value. For example: 


{1 L0« 0 Thee index origin is now 0 


The number of symbols allowed in the active workspace can be 
established only in clear workspace. That is, the size of the symbo/ 
table must be established by the 5110 before any other data is placed 
in the active workspace. 


Symbol Table. Eight bytes of active 
workspace storage are reserved for 
each symbol allowed. 


Active Workspace 


The number of symbols allowed is initially set to 125, which requires 
1000 bytes of active workspace storage. 


There might be times when you have used the maximum number of 

symbols allowed, so you may need to increase the maximum number 
of symbols allowed. If you change the number of symbols allowed in 
a clear workspace and then use the )LOAD command to load a stored 
workspace into the active workspace, the number of symbols allowed 
is the same as when the stored workspace was written to the media. 


However, you can use the following procedure to change the number 
of symbols allowed: 


1. Save the contents of the active workspace using the )SAVE 
command. ; 


2. Clear the active workspace using the )CLEAR command. 


3. Set the new number of symbols allowed using the SYMBOLS 
command. For example: 


ISYMBOLS 25 1—-—\ Now, 251 symbols are allowed. 
WAS 125 
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4. Copy the stored workspace into the active workspace using the 
)COPY command. Using the )COPY command does not affect the 
number of symbols allowed in the active workspace. The )COPY 
command is discussed later in this chapter. 


The workspace identification specifies the device/file number and file 
ID where the contents of the active workspace are stored when a 
)SAVE or )CONTINUE command is issued. The )WSID command can 
be used to change the device/file number and file 1D where the 
contents of the active workspace is to be stored. For example: 


LOAD 11007 TATA 


LOAQED L100 DATA 
—l This device file number and file ID is now | 
IWSTT L2001 TEST associated with the active workspace. 
WAS 11001 DATA 
SAVE 


SAVED 12001 T ae Change the workspace identification. 


Now, when the )SAVE [or )JCONTINUE] 
command is issued, the contents of the 
active workspace are written to the new file. 


GETTING DATA INTO THE ACTIVE WORKSPACE 


You can get data into the active workspace by entering the data from 
the keyboard or reading the data from a tape or diskette file. You read 
data from a tape or diskette file using an APL shared variable or one 
of the following system commands: 

¢ )LOAD 

e )RESUME 

e )COPY 

« )PCOPY 

« )PROC 

See Chapter 10, /nput/Output Control, for information on reading data 


using APL shared variables. The system commands used for reading 
data into the active workspace are discussed next. 


The )LOAD and )RESUME Commands 


The )LOAD and )RESUME commands are used to load an entire stored 
workspace into the active workspace. The contents of the stored 
workspace then replace the contents of the active workspace. The 
)LOAD command has the following characteristics: 


e Loads any stored workspace, which was written to tape or diskette 
by the )SAVE or )JCONTINUE command, into the active workspace. 


e If the stored workspace has a latent expression assigned to the OLX 
system variable, the latent expression is executed each time the 
)LOAD command is used to load that stored workspace into the 
active workspace. 


e If the stored workspace has shared variables established, the shared 
variables are not reestablished when the )LOAD command loads the 
stored workspace into the active workspace. 


The )RESUME command has the following characteristics: 


e Loads any stored workspace which was written to tape or diskette 
by the )SAVE or )CONTINUE command into the active workspace. 


e If the stored workspace has a latent expression, the latent 
expression is not executed when the continued (stored) workspace 
is loaded into the active workspace. 


e The primary reason for using this command is to reestablish the 
system environment as it was when the workspace was written to 
the media. That is, if the stored workspace was written to the 
media by the )CONTINUE command, any shared variables and/or 
suspended functions in the stored workspace are reestablished in 
the active workspace by the JRESUME command. See The 
JRESUME Command in the /BM 5110 APL Reference Manual, 
$A21-9303, for a description of how shared variables are 
reestablished. 
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The )COPY and )PCOPY Commands 


The )COPY and )PCOPY commands are used to copy all or selected 
objects (variables or user-defined functions) from a stored workspace 
into the active workspace. When these commands are used, the 
objects are copied into the active workspace without replacing the 
entire contents of the active workspace. When the )COPY command is 
used, any objects already in the active workspace are replaced by the 
objects specified by the )COPY command if the objects have the same 
name. When the )PCOPY command is used, any objects in the active 
workspace are protected and not replaced by the specified objects if 
the objects have the same name. These commands have the 
following characteristics: 


@ These commands can only be used to copy objects from a 
workspace written to tape or diskette by the )SAVE command. If 
you want to copy objects from a workspace written to tape or 
diskette by the )CONTINUE command, the stored workspace must 
be loaded into the active workspace and then written to the media 
by the )SAVE command. 


e These commands cannot be used if the active workspace contains 
suspended functions. 


e These commands can be used to copy objects from several stored 
workspaces into the active workspace. 


The }PROC Command 


An alternative to entering data from the keyboard is to get the data 
from a procedure file. A procedure file contains character records that 
represent any input that is possible from the keyboard, such as system 
commands, function definition, and APL expressions. When the )PROC 
command is issued, the 5110 reads and executes one procedure file 
record at a time until the last record (end-of-data) is processed. Then 
the 5110 goes back to using regular keyboard input. [See the /BM 
5110 APL Reference Manual, SA21-9303, for a complete description of 
procedure files and the )PROC command.] 


A procedure file must be a type | or U data file and the records cannot 
be greater than 128 characters. (See Chapter 10, /nput/Output 
Control, for a complete description of data files.) 


A procedure file is useful for doing unattended applications that 
require using system commands and/or function definition. For 
example, assume you have an application that requires several 
user-defined functions. However, not enough workspace storage is 
available to contain all of the user-defined functions. In this case, you 
might: 


1, 


Use the )SAVE command to store the user-defined functions on 
tape or diskette. 


Create a procedure file that contains the following character 

records: 

a. A )COPY command to copy the first user-defined function(s) 
required for the application into the active workspace 

b. The statement(s) required to execute the user-defined 
function(s) 

c. An )ERASE command that erases user-defined functions and 
variables that are no longer required 

d. A )COPY command that copies the next user-defined 
function(s) required for the application into the active 
workspace 

The previous steps are repeated until the application is complete. 


Use the )PROC command to execute the statements from the 
procedure file. After the last statement is read and executed, the 
5110 again accepts input from the keyboard. 


Note: Using the )PROC command requires approximately 800 
bytes of active workspace storage. The active workspace is 
always cleared the first time a )PROC command is used after you 
turn the power on or press RESTART, because the required 800 
bytes can be allocated only in a CLEAR WS. The active 
workspace is not cleared for any subsequent )PROC commands 
because the 800 bytes are already allocated until the power is 
turned off or RESTART is pressed. Therefore, if you have any 
useful data in the active workspace, you should save this data 
before using the )PROC command the first time. 
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INFORMATION PROVIDED ABOUT THE ACTIVE WORKSPACE 


You can get information about the active workspace by simply 
entering certain system commands, system variables, or system 
functions without specifying any parameters or arguments. The 
system commands that provide information about the active 


workspace are: 
System Command 


)SYMBOLS 


)WSID 


)FNS 


VARS 


)SI 


)SINL 
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Information Provided 


How many symbols are allowed 
and how many symbols are 
currently being used. (The symbols 
consist of labels, variable names, 
user-defined function names, and 
any system variables and functions 
that have been used.) 


The current workspace ID and 
device/file number. This 

information specifies where the 

active workspace is stored when a 
)SAVE or )CONTINUE command is used. 
(When a stored workspace is loaded 
into the active workspace, the 
workspace ID and device/file 

number of the stored workspace 

is assigned to the active workspace.) 


The name of the user-defined 
functions in the active workspace. 


The names of the variables in the 
active workspace. 


The names of any suspended functions and 
the statement number where each 
function is suspended. For example: 


IST Statement 2 of this function 
FUNCTIONALS J a called FUNCTIONA. 
FUNC TIONG 2 

FUNCTIONCL S61 *———Statement Number 


Function Name 


The * (asterisk) indicates the suspended 
functions. The functions without an 
asterisk are functions (called pendent 
functions) that called the previous 
function. 


The same information as the )S! command 
plus the names local to each function. 


The system variables that provide information about the active 
workspace are: 


System Variable Information Provided 


OCT How different two numbers 
must be to be considered unequal. 


OO The value of the index origin. 


ORL The starting value used in 
generating random numbers. 


OLC The statement number currently 
active. These statement numbers are 
the same as the statement numbers 
displayed by the )SI command. 


OWA The amount of unused storage 
in the active workspace. 


Note: The value of these system variables can be used in APL 
statements. For example: 


+DILC causes a suspended function to resume execution with the next 
statement to be executed. 


The system functions that provide information about the system are: 
System Function Information Provided 
ONL The names of the labels, variables, 
and user-defined functions in 
the active workspace 
ONC The classification (label, variable, 


or user-defined function) of a 
specified name 


ACTIVE WORKSPACE STORAGE CONSIDERATIONS 


Because the 5110 active workspace contains a fixed amount of 
storage, it is good practice to conserve as much storage as possible. 
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Data Types and Storage Considerations 


The following list shows how many bytes of storage are required for 
each data type that can be in the active workspace: 


Data Type Number of Bytes Required 
Character constant 1 byte per character 
Variable name (3 12 + (4.x rank) bytes 
characters or less) The rank is the number of 


coordinates (ppvariable). 


Variable name (4 4 byte per character + 21 
characters or more) bytes + (4 x rank) bytes 


Whole numbers that are 4 bytes 
equal to or less than 
231 4 


Whole numbers that.are 8 bytes 
greater than 2°' -1 


Decimal numbers 8 bytes 


Logical data 1 bit (1 byte contains 
8 one or zero bits) 


Note: Storage is always allocated in 4 byte increments. For example, 
the following illustration represents a portion of storage: 


1 byte 


——— 
poe ee ee eee] oe Sc ed 


In this example, The statement The statement The statement 
storage has been A ~~ ‘ABCD’ X <— ‘EF’ Y -<— ‘GH’ uses 
allocated and used allocates and uses allocates 4 bytes the remaining 

to this point. Also 4 bytes of storage of storage, but 2 bytes. 

the storage required uses only 2 bytes 


for the variable 
names A, X, and Y 
is already allocated. 


Following are some considerations that can be used to conserve 
storage: . 


e Make all objects (variables and user-defined functions) not required 
for use outside of a user-defined function local to the function. 


e Store data in data files on tape or diskette and use an APL shared 
variable (see /nput/Output Contro/) to transfer the data into the 
active workspace when required. 


e Clear suspended functions from the active workspace. 


e Collect user-defined functions by related operations and store each 
set into a workspace file on the media. Then when a certain set of 
related functions is required to process data in the active 
workspace, the stored workspace containing these functions can be 
copied into the active workspace. When the processing is done, the 
functions can be expunged (DEX) and another set of functions can 
be copied into the active workspace. 


e If a value consists of all 1's and O’s, store the value as logical data. 
For example, you have the following vector: 


VECTORGe 10 eaC2—1) 
VECTOR 
tt tt. £2 tS 


The result is a vector of ten 1’s, and each 1 requires 4 bytes of 
storage. However, the vector can be changed to a logical vector as 
follows: 


VECTORG LAVECTOR 


VECTOR 
doy De ee “ek 
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The result looks just like the previous result; however, only 2 bytes 
of storage are required. 


e Because each variable requires at least 12 bytes of overhead, an 
array of six elements requires approximately 60 bytes less storage 
than six separate variables. 


e@ Names of 3 characters or less require 8 bytes of storage in the 
symbol table (the symbol table is part of the active workspace 
where the names of all the symbols, including variables, 
user-defined functions, and labels, are stored). Names of 4 
characters or more require an additional 8 bytes plus 1 byte for 
each character in the name. 


Note: Even if an object is erased from the active workspace, the 
storage used for its name will not be available for use unless the 
contents of the active workspace are written to the media with a 
)SAVE command and then loaded or copied back into the active 
workspace. 


e Identical names that are local to more than one user-defined 
function do not require additional symbol-table space for each 
function. 


When the contents of the active workspace are written to the media 
by the )CONTINUE command, and that stored workspace is loaded 
into a different 5110 with a larger active workspace, the amount of 
available workspace (OWA) remains the same as it was when the 
contents of the active workspace were originally written to the media. 
To take advantage of the additional storage in the larger active 
workspace, write the contents of the active workspace to the media 
using the )SAVE command, then load the stored workspace back into 
the 5110. Also, for the same reason, a workspace written to the 
media by the )JCONTINUE command cannot be loaded into a different 
5110 with a smaller active workspace. 


The following formula shows how much storage in the active 
workspace is required to perform an input or output operation to tape 
or diskette using an APL shared variable (see /nput/Output Control): 


REQUIRED STORAGE = BUFFER + SHARED VARIABLE + 
OVERHEAD 


where: 


e REQUIRED STORAGE is the amount of storage that must be 
available in the active workspace (see NWA) before an input or 
output operation to tape or diskette can be performed. If there is 
not enough available storage, a WS FULL error occurs. 


e BUFFER is the amount of storage required by the data assigned to 
the shared variable. This storage is only used during the 
input/output operation. 


e@ SHARED VARIABLE is the amount of storage required for the data 
assigned to the shared variable. 


@ OVERHEAD is the amount of storage used when the input/output 
operation is specified. The overhead is as follows: 


OUT and OUTF operations—812 bytes 


IN operation—792 bytes 
INR, lOR, IORH operations—356 bytes 
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ADDITIONAL STORAGE USING DISKETTE DATA FILES 


You can use a direct access data file to store variables that are not 
currently needed in the active workspace. These variables can then be 
removed from the active workspace (to conserve storage) and quickly 
read back into the active workspace as needed. You can use the 
following procedure to store variables for later use on a diskette data 
file: 


1. Establish a type M direct access data file (see /nput/Output 
Control) using dummy records. The first dummy record written 
to the file should require as much diskette storage as the largest 
variable that is to be written to the file. For example, you might 
use the following user-defined function to establish a type M file 
with 256 bytes allocated for each record: 


VOUMMY ET AY 
VO MUMMY 0S Xs 
| Tea 
| Xe TSvVoO 'C° 
| Cexe OUTF 11008 The CREAL. STORAGE? TYPE=M’ 
] ¥C O41 TKO) ZERROR 
} LOOP Ce etée' A’ 
] 3(O4 19 XeCO ERROR 
J oC202T¢ Ted) /LOOP 
a 
- 
10 
i 


You must specify the file 
1D enclosed in single quotes. 


Ce 10 
>COF1T tT KE DI /SERROR 
‘I ‘THE TATA FILE IS CREATED SUCCESSFULLY’ 
) 30 
2") ERROR: 'ERROR--THE RETURN CODE TS: ' 4x 
¥ 


2. Establish a pair of shared variables, and specify direct access 
input/output operations to the data file. For example, you might 
use the following user-defined function: 

YOPENCE AV 
Y OPEN FILETO,; 


x 


Cid Xe [1SVO 2 7 p'CTLSAVEDATSAVE' 

[2] 9Ca/X#2)/ERROR 

C3] CTLGAVE*' TOR I= (',FILEID,')' — You must specify the 
: : : arrrclee RRORD file 1D enclosed in 

oe Bed oe , AL JT e H 

[4] ‘SUCCESSFUL OPERATION’ single: quotes: 

ivr GAVEDTISTE 415° ° 

cal 30 

CO) ERRORI'THE OFFER FAILED--THE RESULT TS: ',#X 
clo1 30 

Cli ERROR®?: THE OPEN FALLED--THE RETURN CODE: ‘, +X 


V 


3. Store the variable in the data file. For example, you might use the 
following user-defined functions: 


The left argument must be 1 to 
expunge the variable name from 
the active workspace; otherwise, 
the left argument must be 0. 


The right argument is the variable 
name enclosed in single quotes. 


VSAVELLINY 
¥V EXPUNGE “SAVE VAR; MASK: X. 
Rad ACO@(INC 'SAVELIST'O/S'SAVELISTed Getto tt! 
C2 tC CaSAVELTSTICL I“ pVARe, VAR) /'SAVELISTe&SAVELIST BY VAR’ 
C3 £ (vv /MASKe COC OSAVELISTILCILITVAR A, =SAVELISTIO/'SAVELIST © 
SAVELIST BY VAR' 


iy I NLe CeSAVELISTIOA 
CS] TATSAVEGAVAR 
C42 CTLGAVE ST, CCONLT VARA &@SAVELISTOAd 
ar ae | +047 ETLSAVE) /ERROR 
C8 Xt 
9 7 tEXPUNGE /'X¢(HEX ‘' VAR, ' 
E1071 “THE VARTABLE [95 SAVED °', ¢X/' ANT EXPUNGED') 
riid 30 
R120 ERROR! ‘SAVE FATLEINU 

¥ 

VBEYCT AV This function is used 


nog OEY Be Re oe by the SAVE function: 
CLI AeC2tC PAD, 1 1) 0A 

C2] BeC2tieB), 1 Lek 

C31 ROWeLt Coad Tek 

CHT AECROW, “1 tea) tA 

CSI BeCROW, “1 teB) +B 

c4]  Zea,B 


4. Ata later time, read the stored variable back into the active 
workspace. For example, you might use the following 
user-defined function: 


The right argument is the 
VEE TCHEU AY 7 variable name enclosed 
¥ ZeFETCH VAR; MASK: NL in single quotes. 
a ie SCQ=(INC 'SAVELIST' )/NOTFOUND 
C27] 3CCeVARGe , VARI SNLELt pi iee TST) /NOTFOUNT 
37 3a Cav/MASKe CNLTVAR IA, =SAVELIST) /NOTFOUNT 
Cu CTLSOAVE¢O, MASK iL 


even even snen ove 


CSI) -4C0#+7ETLSAVE) £0 

C6] ZeVAR,' IS” FGuNn' 

[71 aVAR, ‘¢llATSAVE’ 

[C8] 40, DATSAVECTO 

COI) NOTFOUNTTZevarR,' IS NOT FOUND IN THE FILE’ 
v 


Active Workspace Control 55 


56 


5. Before the contents of the active workspace can be written to the 
media by the )SAVE command, the input/output operations to the 
data file must be terminated. For example, you might use the 
following user-defined function: 


YCLOSECINTY . 

¥ CLOSE FILETY You must specify the file 1D 
CTLGAVES aol enclosed in single quotes. 
Xe CTESAVE 
COLT KI/CERROR 
‘THE FILE CLOSED SUCCESSFULLY’ 
oat 


oe ae ome | 
a el 


wi ¢ 
ai Oh 
e322 to bg Le bad 


a 
y 


Note: \f you want to use the data file at a later time, do not 
terminate the input/output operations. Instead, you should use 
the )CONTINUE command to write the contents of the active 
workspace to the media and then use the )RESUME command to 
reestablish the input/output operations at a later time. 


This procedure works as follows, using the sample user-defined 
functions: 


IMARK 1048 11.——_—— File number 8 is used as 
MARKED 0008 0010 the data file. 


MY <———————__- Create the data file 
THE TATA FILE [SS CREATED SUCCESSFULLY used to save the 
variables. 


OPEN ‘REAL, STORAGE '«——— The data file is ready 
SUCCESSFUL OPERATION for input/output operations. 


A variable to 
be saved for later 
use. 


TNF ORMATIONG '@ PROGRAMMING LANGUAGE ' 


ERRORS THE FILE G20 NOT CLOSE--THE RETURN COG Pes’ 


The variable is to be expunged. 


1 SAVE 'TNFORMAT TION ' 
THE VARTARBLE TS SAVED ANT EXPUNGER 


INFORMATION 
VALUE ERROR = +—_____ The variable no longer exists in the 


THETIRMATTSL 
ha ORMATION active workspace. 


FETCH ‘INFORMATION 
INFORMATION IS FOUNT Tee 
Read the variable back into 


the active workspace. 
THF ORMAT TON ae 
A PROGRAMMING LANGUAGE 


APLe TTA’ 


The variable is saved, but it is 
ee not expunged. 


0 SAVE "APL 
THE VARTABLE IS SAVEL 


APL 
ATA 


A variable not saved in the 
ae data file. 
FETCH "NAME 


NAME TS NOY FOUND IN THE FILE 


etude the active workspace 
can be saved, the data 
file must be closed. 


CLOSE “REAL. STORAGE ' 
THE FILE CLOSED SUCCESSFULLY 


Active Workspace Control 


57 


58 


Chapter 5. Console Control 


The 5110 console consists of a keyboard, a display screen, and 
switches. 


In this chapter, the following topics concerning the 5110 console are 
discussed: | 


e Controlling the input from the keyboard 
e Controlling the position of the information on the display screen 
e Sounding the audible alarm 


e Console control through a user-defined function 
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CONTROLLING THE INPUT FROM THE KEYBOARD 


The following illustration shows the positions on the alphameric 
keyboard of the uppercase alphameric characters, the APL symbols, 
the APL keywords, and the special character combinations: 


; COPY 
(a5) CRE) CT) 


Note: The special character combinations are engraved on the front of 
the appropriate key on the 5110 keyboard. If the 51 10 is a 
combination APL/BASIC machine, the special APL character 
combinations are below the BASIC keywords. 


When you turn the 5110 power on, the 5110 is in standard APL 
character mode. That is, you enter the uppercase alphabetic 


characters without using the shift o<—D key, the APL symbols 


using the shift key, and the APL keywords and special character 
combinations using the CMD key. For example, if you press: 


The character A is entered from 
the keyboard. 
eS The character a is entered from 
(ea) the keyboard. 
} The character combination OWA 
is entered from the keyboard. 
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You can also enter lowercase alphabetic characters from the keyboard. 
To do this, you use one of the following procedures: 


e Use the keying sequence: 


1. Press the key. 
2. Hold down a > he key and press the (scroll 


down) key. 


e Enter the following statement to use the console contro! (DCC) 
system function: 


A 3 as the left argument specifies that the OCC system 


r function is used to change the character mode. 


Specifies lowercase alphabetic characters. (See the 
/BM 5110 APL Reference Manual, SA21-9303, for a 
complete description of the DCC system function.) 


Once the 5110 is in lowercase character mode, you enter the 
lowercase alphabetic characters without using the shift key, the 
uppercase alphabetic characters using the shift key, and APL 
symbols using the CMD key. For example, if you press: 


The character a is entered from 
Htc the: keyboard. 
he ) The character A is entered from 
Rad the keyboard. 
i The character a is entered from 
the keyboard. 


You cannot enter the special character combinations using the CMD 
key and a single key when the 5110 is in lowercase character mode. 
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The 5110 remains in lowercase character mode until: 

e The system power is turned off. 

e The RESTART switch is pressed. 

e One of the following procedures is used to change the keyboard 


entry mode to standard APL characters: 
-- Perform the keying sequence: 


1. Press the key. 
2. Hold down “is key and press the (scroll 


up) key. 
-- Enter the statement: 


$8 FCC o 


Specifies standard APL character mode 


CONTROLLING THE INFORMATION ON THE DISPLAY SCREEN 


You can control the information and the position. of the information on 
the display screen by using: 


@ The scroll up and scroll down keys 


@ The DCC (console control) system function to turn display on or off 


e The OCC system function to scroll the information on the display 
screen up or down 


e A pair of shared variables 


You are already familiar with using the scroll up and scroll down keys 
to position the information on the display screen. How to use a pair of 
shared variables to read and write data at any position on the display 
screen is discussed in detail under /nput/Output Contro/. How to use 
the OCC system function to control information on the display is 
discussed in this section. 


Using the DCC System Function to Control on the Display Screen 


In the previous discussion on controlling the input from the keyboard, 
the OCC function was used to place the 5110 in lowercase alphabetic 
character mode. The [ICC function can also be used to: 


e@ Turn the display screen on or off during the execution of a 
user-defined function. The primary advantage in turning the display 
screen off is that the 5110 internal processing speed is increased by 
approximately 18%. 


e Scroll the information on the display screen up or down. 


To turn the display screen off during the execution of a user-defined 
function, the left argument of the DCC function must be a 1 and the 
right argument must be 0. The display screen remains off until one of 
the following occurs: 


e The user-defined function completes execution. 


e The OCC function is used to turn the display screen on again (both 
the left and right arguments are specified as 1). 


e A later statement in the user-defined function generates a result to 
be displayed. 


Since the OCC function generates an explicit result, that result must be 
assigned to a variable to prevent the display screen from being 
immediately turned on and the result displayed. For example: 


Pid Red GCC oO. 


When the OCC function is used to scroll the display screen up or 
down, the left argument must be 4 and the right argument specifies 
the number of lines to scroll up or down. For example: 


Rel TCC 8 Scrolls the information on the display screen 
up 8 lines 
Rel. IOC "iS Scrolls the information on the display screen 


down 3 fines 


In the previous examples, the explicit result of the DCC function is 
assigned to a variable. Otherwise, the explicit result is displayed after 
the OCC function scrolls the display screen up or down. 
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SOUNDING THE AUDIBLE ALARM 


Another use of the DCC function is to sound the audible alarm feature, 
if installed. To do this, the left argument must be a 2 and the right 
argument is: 


e A 1 to sound the audible alarm. The audible alarm remains on until 
any input is entered from the keyboard or the OCC function is used 
to turn the audible alarm off (the right argument is a 0). For 
example: 


Re? TCC 1 0 1 @ J 8 
turns the audible alarm on and off three times. The on/off interval 


is approximately 0.006 second. 


e A vector of 2’s, where each 2 sounds the audible alarm for 
approximately 1/4 second. For example: 


Re? TIC 2 2 2 @ 


ae 


sounds the audible alarm four times for approximately 1/4 second 
each time. 


CONSOLE CONTROL THROUGH A USER-DEFINED FUNCTION 


The OCC system function, like any other system function, can be 
executed from a user-defined function. This technique allows the 
following console control operations to be initiated from a 
user-defined function: 


e Turn the display screen on or off. 


@ Sound the audible alarm. 


@ Set the keyboard input to standard APL characters or lowercase 
alphabetic characters. 


@ Scroll the display screen up or down. 


@ Set the left tab position for printed output (see Printer Control! for 
more information on ‘setting the left tab position). 


Following is an example of initiating console control operations from a 
user-defined function: 


ae 


2s 


mm ot 
Fie lel 


APO. oF 
£ <2. 8 2:28 


tt 
MG t 
we so 8s 
See Seeeees 


met 
"ore 
_ bf ii 


Scroll the display screen up 16 lines. 
VCONTROLEE TY 

CONTROL: NAME: STATEMENT: R 
Rey [IOC 14 
Res FCC 
"ENTER YOUR FIRST AND LAST NAME 
NAME [] 


Set the keyboard input to lowercase 
alphabetic character mode. 


Pome 


Rel (Cl 10 APL character mode. 

Me WELCOME * 

Ne NAME 

‘y ENTER A STATEMENT TO RE EXECUTED, | 

Rel [ICC 2 

STATEMENT €[] 

a ee ; “Turn the display screen off to improve 


Rea STATEMENT internal performance when the next 
‘THE RESULT TS: ° pastels eneeuted: 
R 
Reo [JC 2 2 2 2 
The display screen is turned on again when 
output is sent to the display screen. 


Sound the audible alarm when the user-defined 
function has completed execution. 
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Chapter 6. Library Control 


The tape or diskette files where you store information is your /ibrary. 
In this chapter, the following topics concerning the 5110 library control 
are discussed: 

e Determining the size of a tape or diskette file 


e Writing data to a tape or diskette file 


@ Getting data from a tape or diskette file 


Controlling files in the library 
e@ Maintaining data security 


References are made to some of the 5110 system commands: for 
example, the )MARK command or the JRESUME command. See the 
IBM 5110 APL Reference Manual, SA21-9303, for a complete 
description of the system commands. The description includes the 
required syntax for each system command. You must use the proper 
syntax to enter a system command so that the 5110 will accept that 
command. 
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DETERMINING THE SIZE OF A TAPE OR DISKETTE FILE 


Before information can be stored on the media (tape or diskette), the 
media files must be formatted by the JMARK command. When using 
the )MARK command, you can use the following formulas to 
determine the maximum size a file should be marked. The formula for 
a workspace file [the contents of the active workspace were written to 
the storage media with a )SAVE or )CONTINUE command] is MAXSIZE 
= [3 + (CLEAR-ACTIVE) + 1024, where: 


e MAXSIZE is the maximum amount of media storage (number of 
1024-byte blocks) that would be required to write the contents of 
the active workspace to the media. 


e CLEAR is the value of OWA in a clear workspace. 


e ACTIVE is the value of DWA just before the contents of the active 
workspace are written to the media. 


The formula for a data file (data written to the media using an APL 
shared variable) when all of the data is contained in the active 
workspace is MAXSIZE = [ (WITHOUT-WITH) + 1024, where: 


e MAXSIZE is the maximum amount of media storage (number of 
1024-byte blocks) required to write the data to the media. 


e@ WITH is the value of DWA with the data in the active workspace. 


e WITHOUT is the value of DWA before any data to be written to 
tape or diskette was stored in the active workspace. 


There is no formula for determining what size to mark a data file when 
the data is written to the media as it is entered from the keyboard. 
The amount of storage required depends upon how much data is 
entered from the keyboard and what type of data is used. For 
information on how many bytes of storage are required by the various 
types of data, see Storage Considerations in the Active Workspace 
Contro/ chapter. 


WRITING DATA TOA TAPE OR DISKETTE FILE 


You can write data to a file by using the )SAVE command, the 
)CONTINUE command, or an APL shared variable. The )SAVE or 
)JCONTINUE commands are used to write the contents of the 5110 
active workspace to a file. An APL shared variable is used to write 
individual data records to a data file (shared variables are discussed in 
detail under /nput/Output Contro/). . 


The following list shows the advantages and disadvantages of using 
the )SAVE command versus the )CONTINUE command. You should 
consider these advantages and disadvantages when choosing which 
command you are going to use when writing the contents of the 
active workspace to the media. . 


Using the )SAVE Command 

Advantages: 

e The stored workspace can be loaded into a 5110 that has a smaller 
active workspace than the original active workspace, providing the 
stored workspace does not require more storage than is available in 
the smaller active workspace. 

e The additional storage is available to the user when the stored 
workspace is loaded into a 5110 that has a larger active workspace 


than the original active workspace. 


e The symbol table is cleared of unused or expunged symbol 
references. 


e The )COPY and )PCOPY commands can be used to copy specified 
variables or user-defined functions from the stored workspace. 


Disadvantages: 


@ The active workspace is not written to the media as fast as when 
the )JCONTINUE command is used. 


e The stored workspace is not loaded into the active workspace as 
fast as when the )CONTINUE command is used to write the 


workspace to the media. 


@ If the active workspace contains suspended functions or open data 
files exist, the active workspace cannot be written to the media. 
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Using the JCONTINUE Command 


Advantages: 


7 


Even if the active workspace contains suspended functions or open 
data files exist, the active workspace can be written to the media. 
Any open data files or suspended functions can be restored by the 
)RESUME command. The )RESUME command is discussed in more 
detail under Getting Data from a Tape or Diskette File in this 
section. 


The active workspace is written to the media faster than when the 
)SAVE command is used. 


The stored workspace is loaded into the active workspace faster 
than when the )SAVE command is used to write the workspace to 
the media. 


Disadvantages: 


The )COPY and )PCOPY command cannot be used to copy variables 
or user-defined functions from the stored workspace. 


The stored workspace can only be loaded into a 5110 with an active 
workspace at least as large as the original active workspace. 


The additional storage is not available to the user when the stored 
workspace is loaded into a 5110 that has a larger active workspace 
than the original active workspace. 


GETTING INFORMATION FROM A TAPE OR DISKETTE FILE 


You can read information from a tape or diskette file by using the 
)LOAD, )RESUME, )COPY, )PCOPY commands, or an APL shared 
variable. The )LOAD, )COPY, )PCOPY, and )JRESUME commands are 
used to place the contents of a stored workspace into the 5110 active 
workspace. An APL shared variable is used to read individual data 
records from a data file (shared variables are discussed in detail under 
Input/Output Control). 


Generally, you use the: )LOAD command to replace the contents of the 
active workspace with the contents of a stored workspace. However, 
if there were shared variables or suspended functions in the active 
workspace and the )CONTINUE command was used to write the active 
workspace to the media, the RESUME command reads the stored 
workspace into the active workspace and reestablishes the shared 
variables and/or suspended functions. That is, the system 
environment is reestablished as it was when the )CONTINUE command 
was issued. 


Using the )CONTINUE and )RESUME commands allows you to work 
with shared variables or suspended functions, write the active 
workspace to the media, and then reestablish the system environment 
at a later time so that you can continue working with the shared 
variables and/or suspended functions. See The JRESUME Command 
in the /BM 5110 APL Reference Manual, SA21-9303, for a description 
of how the shared variables are reestablished. 


If a workspace was stored on the media using the )SAVE command, 
you can copy all or part of that workspace into the active workspace 
by using the )COPY or )PCOPY commands. The )COPY command 
copies all or specified objects (variables or user-defined functions) into 
the active workspace and replaces any objects in the active workspace 
that have the same name. The )PCOPY command copies all or 
specified objects into the active workspace; however, any objects in 
the active workspace that have the same name are not replaced (they 
are protected). The )COPY and )PCOPY commands allow you to read 
more than one stored workspace or parts of more than one stored 
workspace into the active workspace without replacing objects already 
existing in the active workspace. 
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CONTROLLING THE FILES IN THE LIBRARY 


Once you have stored several workspace and data files on a tape or 
diskette (your library), you might want to know what files you have in 
your library. You can use the )LIB command to display the file headers 
for a specified tape or diskette. The file headers provide you with 
such information as the file number, the file ID, the file type, and so 
on. See The JL/IB Command in the /BM 5110 APL Reference Manual, 
SA21-9303, for a description of the information contained in the file 
header. 


When there are files on tape or diskette that contain data that is no 
longer required, you can mark these files unused by issuing the )DROP 
command. Once a file is marked unused, any data in the file can no 
longer be read into the 5110 and the file is available for other uses. 


Also, if a diskette file is no longer required, you can make the file 
space available for reallocation by issuing the )FREE command. This 
allows the file space on the diskette to be used for other numbered 
files by the JMARK command. See Diskette Concepts for more 
information on how files are allocated on a diskette. 


DATA SECURITY 
You are primarily responsible for the security of any sensitive data. 
After you are through using the 5110, you can remove the data in the 
active workspace by one of the following: 
e Using the )CLEAR command to clear the active workspace 
e Pressing the RESTART switch 
e Turning the POWER ON/OFF switch to off 


There are several methods available for protecting or removing 
sensitive data on a tape or diskette. These methods are: 


e Assigning a password to the workspace when the system is writing 
the active workspace on the media. 


e Rewriting a file, which makes the old data inaccessible. 


e Filling a data file with meaningless data. For example, the following 
user-defined function fills file 4, a data file named DATA on tape 1, 


with zeros: 
YSECURTITY:; 4A; 5 
Pid 2 FSvo "at 
R20 Ae OUT 2OOu The cata? ' 
4 Belo LO00e0 
Pu T WRI AtK 
Bc 


SCALLI=0)/WRY 


e Setting the tape cartridge SAFE switch in the SAFE position to 
prevent someone from accidently writing on the tape. 


e Using the PROTECT command to prevent someone from accidently 
writing on a diskette file. 


e Using the )VOLID command to prevent unauthorized access to the 
diskette files. 


e Storing the tape or diskette in a secure place. 
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Chapter 7. Tape Concepts 


There are 204K bytes (1K = 1024 bytes) of tape storage available on 
an IBM Data Cartridge. This tape storage is used for file headers, 
workspace files, and data files. In this section, the following topics are 
discussed: 


e How to format the tape 


e@ How to determine the amount of storage on a tape cartridge that is 
actually available to you 


FORMATTING THE TAPE 


You must use the )MARK command to format files on the tape before 
you can store the contents of the active workspace or data records on 
the tape. For example: 


MARK 10 SW 


a Starting File Number 


Number of Files to Mark 


Size of the Files in Increments of 1,024 (1K) 
Bytes. In this case, the size of the marked 
files is 10, 240 (10 x 1,024) bytes. 


Once the previous )MARK command is successfully completed by the 
5110, the tape is formatted as follows: 


File Headers This file header 
indicates end of 
marked tape. 


This hole indicates Each file-contailis Unformatted 
the beginning of 10,240 bytes of Tape 
the tape storage. : 

storage. 
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The file headers contain information about the file, such as the file 
number, file name, file type, and so on. Each file header requires 512 
bytes of tape storage. 


Now, if you want to format additional files on the tape, you must use 
the )MARK command again. For example: 


1 4 
| Starting File. Remember, in this 


example, five files are already 
formatted. 


MARK 20 


Number of Files to Mark 


File Size 


The tape is now formatted as follows: 


File 6 Header 


File 6 is formatted Unformatted 
after file 5. Tape 


When the information in a tape file is no longer needed, you can use 
the )DROP command to mark the file unused so that the file is 
available for other uses. However, once a file is formatted, you 
cannot increase the size of the file without re-marking the file. When 
you re-mark an existing file, any information in the files following the 
re-marked file is lost. For example, assume you want to increase the 
size of file 4 on the tape from 10K to 15K: 


LET = I 


You want to increase the size 
of file 4 by 5K. 


After the command: 


File Size 
Number of Files to Format 
Starting File Number 


MARK TS 1 & 


is successfully completed, the tape is formatted as follows: 


ALIX 


File 4 now contains This file header now indicates the end of 
15K bytes of tape storage. the marked tape, and any data following 
this file header is lost. 


A formatted tape has the following characteristics: 


e The files are of variable length from 1K to 200K, in 1K increments. 


. @ The files can be randomly accessed; that is, you can read a file 
without having to read the previous file. However, the data in the 
files must be accessed sequentially. 


@ It can contain both workspace and data files. 


e It can contain both APL and BASIC files. 
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DETERMINING THE AMOUNT OF STORAGE AVAILABLE ON A TAPE 
CARTRIDGE 


There are approximately 204K bytes of storage on each tape cartridge, 
but the amount of tape storage actually available to you depends on: 


@ How many files are marked (formatted) on the tape 
® How the data files were written to tape 


Each file on a tape cartridge requires one 512-byte file header. 
Therefore, as you mark more files on a tape cartridge, more tape 
storage is used for file headers. For example, if you mark one 3K file 
on a tape, 512 bytes of tape storage are used for the file header. 
However, if you mark three 1K files on tape, 1,536 bytes of tape 
storage are required for the file headers. 


One 3K File 


Jose es 


Three 1K Files 


Tex «fox [_ «Tox Tl 


Notice that, in each case, a total of 3K bytes of tape storage is 
allocated for tape files. However, in the second case, an additional 1K 
bytes more of tape storage are used. 


The amount of data you can store in a data file depends on how the 
data is written to the data file. (See /nput/Output Control for a 
complete description of writing data to data files.) For example, when 
you first write data to a data file (an OUT operation), the individual 
records are sequentially written to tape starting at the beginning of the 
data file. Once these records are written to tape, the data file might 


look like this: 
Data File 
Beginning of the Last Data Record Unused End of the 
Data File Tape Storage Data File 


Now, assume you add data to the data file at a later time (an ADD 
operation). The new data starts at the first.512-byte boundary after 
the last record in the data file. The tape storage between the last data 
record and the additional data records is unavailable for use. Once the 
new data records are written to tape, the data file might look like this: 


512-Byte Boundaries (tape storage is 
divided into 512-byte segments) 


Data File pone Cy 
| | | | | | | | | | 


\ an / 


Beginning of Unavailable Last Data Record Unused 
the Data File Tape Storage Tape Storage 


As you add more data to the file, it is possible for more tape storage 
to become unavailable. You can compress the data in the data file (use 
the unavailable storage) by first reading all the data records from the 
file and then writing the data records back to the file, starting at the 
beginning of the data file (an OUT operation). 
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Chapter 8. Diskette Concepts 


The IBM diskette is a thin, flexible disk permanently enclosed in a 
semirigid, protective, plastic jacket. When the diskette is properly 
inserted in the diskette drive, the disk turns freely within the jacket. 
The diskette is inserted in the diskette drive as follows: 


Sep eee 
MM 
Case 


ag 


| 


This label must be in the 
lower corner as the diskette 

is inserted in the diskette drive. 
The diskette drive door must be 
closed and latched after the 
diskette is inserted. 


Data is written on the diskette at specific locations (addresses) by the 
system. These addresses provide direct access to specific 
information. Data written at an address remains there until it has been 
replaced by new data. To read data, the desired address is found and 
the data is read into the 5110. 


Before being shipped to a user, each IBM-supplied diskette is 
initialized. Initialization is a process whereby label information and data 
addresses are recorded on the diskette. In this chapter, the following 
topics are discussed: 

e Diskette wear 

e Diskette addressing and layout 


e Diskette types and formats 


e Diskette initialization 
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Diskette volume ID, owner ID, and access-protect indicator 


® Diskette file information, such as file ID, write-protect indicator, and 
organization 


o Reallocation of diskette file space 


o Amount of storage available on a diskette 


DISKETTE WEAR 


The use of flexible diskette storage provides some significant 
advantages, such as low cost, compact size, multiple system functions, 
and ease of media handling and storage. It should be recognized, 
however, that during recording and reading, the read/write head is in 
contact with the media, causing diskette wear over time. Variations in 
the rate of wear will depend on the particular operating environment 
and application characteristics. Care in the storage, use, and handling 
can also affect diskette life. (See guidelines in the /BM 5770 APL 
Reference Maual.) Excessive wear, handling, or contamination can 
cause possible failures in recording and/or reading. 


Ultimate wear is to some extent dependent upon total usage of 
individual tracks. Care taken to distribute data so that accessing 
occurs over the entire recording surface with about the same 
frequency can extend the useful life of the diskette. Actual experience 
with individual applications and environments will allow development 
of guidelines as to when the media should be replaced. 


Unpredictable circumstances such as contamination or severe handling 
can cause an early error to occur. 


For the previous reasons, consideration should be given to providing 
an adequate recovery plan, such as: 


® Backing up critical programs and data files on a second diskette for 
use in the event of an error on the primary diskette. : 


® Periodically moving frequently used files to alternate locations on 
the diskette (see the copy function in the /BM 5770 Customer 
Support Functions Reference Manual). 


DISKETTE ADDRESSING AND LAYOUT 


A diskette address consists of a combination of cylinder number, head 
number, and record number as follows: 


cc H RR 


oe Record (sector) Number. The sector into which the data 


is to be written or from which the data is to be read. 


Head Number. The side of the diskette on-which the data is to 
be written or from which it is to be read. This number is hex 0 
for all one-sided diskettes and for side 0 of two-sided diskettes. 
The number is hex 1 for side 1 of two-sided diskettes. 


Cylinder Number. This number identifies the cylinder onto which a 
physical record is written or from which it is read. 


Track and Cylinder 


A track is the recording area on a single diskette that passes the 
read/write head while the disk makes a complete revolution. The 
read/write head is held by a carriage that can be moved to 77 distinct 
locations along a straight line from the center of the disk. Therefore, 
each diskette has 77 concentric tracks on which data can be stored. 


77 Tracks 


The diskette drive for two-sided diskettes has a read/write head on 
each side. Each track on side 0 of a two-sided diskette has an 
associated track on side 1. 


A cylinder is one track on a one-sided diskette or a pair of associated 
tracks (the corresponding tracks on opposite sides of the diskette) on 
a two-sided diskette. There are 77 cylinders (numbered 0 to 76) ona 
diskette. 
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Sector 


A sector is a portion of a cylinder. All sectors on a single cylinder are 
the same size, and the number of sectors on a cylinder depends on 
the number of bytes per sector (see Diskette Types and Formats in 
this chapter). 


Track 00 


One Sector 


Index Cylinder 


Cylinder 0 is called the index cylinder and is reserved for information 
describing the diskette and its contents. It contains information about 
the diskette, such as volume and owner identification. The index 
cylinder also contains information associated with each file on the 
diskette. This includes the name of each file and the addresses 
associated with the file extents. An extent is the maximum space a file 
can occupy. The address at the beginning of this space is called the 
beginning of extent (BOE). The address at the end of this space is 
called the end of extent (EOE). A file may not use all of the space 
allocated for it by the BOE and EOE addresses; therefore, another 
address for end of data (EOD) exists. 


Actual space being used for data 


—— 
BOE EOD EOE 


Area allocated for the file (extent) 


The EOD address is used to identify the next unused area within the 
extent or to indicate that data has been written to the EOE address. 
(See the diskette initialization function in the /BM 5710 Customer 
Support Functions Reference Manual, SA21-9311, for a complete 
description of the index cylinder.) 


Alternate Cylinders 
The last two cylinders (75 and 76) are reserved for use as 
replacements (alternate cylinders) for defective cylinders. The 
remaining cylinders (1 through 74) are used for storing data. 
DISKETTE TYPES AND FORMATS 
The 5110 uses three types of diskettes; the one-sided diskette (1), 
with data recorded on just one side; the two-sided diskette (2), with 
data recorded on both sides; and the two-sided diskette (2D), with 
data recorded on both sides at double density. The diskettes are 
initialized (see Disk Initialization) into various formats consisting of: 
e The number of sectors per cylinder 


e@ The number of bytes per sector 


The possible diskette formats are: 


Sectors Sectors Bytes 
per per per 
Track Cylinder Sector 
26 26 128 
Diskette 1 15 15 256 
8 8 512 
26 52 128 
Diskette 2 15 30 256 
8 16 512 
26 52 256 
Diskette 2D 15 30 512 
8 16 1,024 


Note: The diskette types (1, 2, or 2D) are identified on the diskette 
label, and the )VOLID command can be used to determine the bytes 
per sector (record size). 
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DISKETTE INITIALIZATION 


The diskettes must be initialized before they can be used for storing 
data. All IBM-supplied diskettes are initialized before they are shipped 
to a customer. Reinitializing is not required unless: 


e The diskette was exposed to a strong magnetic field. 


e A defect occurred in one or two cylinders. In this case, initialization 
can be used to take the bad cylinder(s) out of service and use one 
or two of the alternate cylinders. 


e A sector sequence other than the sequence existing on the diskette 
is desired. 


e A format (number of sectors per cylinder) other than the existing 
format is desired. 


See the /BM 5110 Customer Support Functions Reference Manual, 
SA21-9311, for a description of the diskette initialization function. 


VOLUME ID, OWNER ID, AND ACCESS PROTECTION 


Each initialized diskette has volume ID, owner ID, and an 
access-protect indicator. The volume ID is the identification of the 
diskette volume, and the owner ID is the identification of the diskette 
volume owner. The access-protect indicator is used to prevent 
unauthorized access (reading and writing) to the diskette volume. 


The )VOLID command is used to display or change the volume ID and 
owner ID or to change the access-protect indicator. 


FILE ID 


Each file header on a formatted (marked) diskette has a file ID 
(identification). When the diskette files are formatted, a file ID is 
automatically generated, even though the files are unused. For 
example, the file name for file 1 is SYSO001. 


The )FILEID command can be used to display or change a file ID. 
The file ID for a stored workspace must be a simple name. A simple 
name must begin with an alphabetic character and can be up to eight 
alphameric characters. For example: 

SALES200 
The file ID for a data file can be a simple or complex name. A 
complex name is two or more simple names with each name 


separated by a period. A complex name cannot exceed 17 characters 
including the period. For example: 


SALES200.DATA 


SALES.DATA.DIST12 


DISKETTE FILE WRITE PROTECT 


Each file header contains a write-protect indicator. When the 
write-protect indicator is on, no data can be written to the file. The 
)PROTECT command invokes or removes the write-protect indicator 
for a diskette file. 
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DISKETTE FILE ORGANIZATION 


You use the MARK command to format files on the diskette before 
you can store workspaces or data records on the diskette. For. 
example: 


MARK 10 5S 2 1d 


—— Diskette Drive 1 


Starting File Number 
Number of Files to Format 


Size of the Files in Increments of 1,024 (1K) Bytes. In this case, 
the size of the marked files is 10,240 ( 10 x 1,024) bytes. 


Unlike tape files, the diskette files are not always formatted 
sequentially on the diskette. For example, file 2 might be on cylinder 
3, file 3 on cylinder 9, and file 4 on cylinder 7. You can control the 
location of a file on the diskette only by using a totally unmarked 
diskette and issuing )MARK commands in the same order as the files 
are to be formatted on the diskette. 


When the information in a diskette file is no longer needed, you can 
use the DROP command to mark the file unused so that the file is 
available for other uses. However, once a file is formatted, you cannot 
increase the size of the file without re-marking the file. Reallocating 
diskette file space is discussed next. 


REALLOCATING DISKETTE FILE SPACE 


Unlike tape files, when you re-mark an existing diskette file, no other 
diskette files are affected. When you re-mark a diskette file to 
increase the size, the file space presently allocated to that diskette file 
is made available for other files being marked. The remarked file will 
then be located on the diskette where there is enough continuous 
storage available for that file. For example, assume you want to 
increase the size of file 4 from 10K to 15K by issuing a )MARK 15 1 4 
11 command: 


Disk 
Cylinder 


pe eee 7/7 


After you issue the )MARK command 
this file space is no longer allocated 
for File 4. 


Once the file space previously occupied by file 4 is available, that file 
space will be used by a subsequent )MARK command that marks a file 
of 10K or smaller. 


After the )MARK command is successfully completed, file 4 is 
formatted on the diskette at a location where at least 15K of 
continuous storage is available. : 


Diskette 

Cylinder 

Another \ 

Diskette Unallocated Diskette Storage 
Cylinder ! 


e/a 


20K of unallocated diskette storage was 
available at this location before the 
)MARK command was issued. 
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AMOUNT OF STORAGE AVAILABLE ON A DISKETTE 


The amount of storage available on a diskette depends upon: 


e Whether data can be recorded on just one side or on both sides of 
the diskette 


e The number of sectors per cylinder 
e The number of bytes per sector 


Each diskette has 77 cylinders. Cylinder 0 is the index track and is 
reserved for information (file headers) about the diskette files. 
Cylinders 75 and 76 are alternate cylinders that are used as 
replacements for bad cylinders. This leaves cylinders 1 through 74 
available for data storage. The following chart shows the amount of 
storage available with the different types of diskettes: 


Sectors Bytes Available 
per per Storage in Bytes 
Cylinder Sector (cylinders 1-74) 
26 128 246,272 
Diskette 1 15 256 284,160 
8 512 303,104 
52 128 492,544 
Diskette 2 30 256 568,320 
16 512 606,208 
52 256 985,088 
Diskette 2D 30 512 1,136,640 
16 1,024 1,212,416 


Although the previous chart shows the maximum amount of diskette 
storage, the amount of diskette storage actually available to you 
depends on: 

© The number of files and the size of the files marked on the diskette 


© The types of data files that are written to the diskette 


® The allocation of file space as the result of previous )MARK and 
)FREE commands 


Number and Size of Diskette Files 


The diskette volume/owner identification (7 sectors) and file header 
information are contained on the index cylinder. The remaining 
cylinders on each type of diskette can have the following maximum 
number of files: 


Diskette 1 Diskette 2 Diskette 2D 


Maximum Number 
of Files 19 45 71 


Note: For a type 2D diskette, see the disk initialization function in the 
IBM 5110 Customer Support Functions Reference Manual, SA21-931 Ay 
for information on how to get additional file headers. 


If you mark the maximum number of files without using all the 
available file space, the remaining file space becomes unavailable for 
storing data. For example, assume you have an unmarked Diskette 1 
with 128 bytes per sector. This diskette has 246,272 bytes available 
for storing data; however, you issue the following command: 


MARK 10 197 1 1d 


| en this example, diskette drive 1 is used. 


The starting file number. 


The number of files to be marked. 


The size of each file to be marked. 


This command marks the diskette with the maximum 19 files. Because 
each file is 10K bytes, a maximum of 190K (194,560) bytes of storage 
is allocated for the files. Now, if you subtract the allocated diskette 
storage from the available diskette file space: 


246,272 
—194,560 


51,712 For this example, this much diskette storage is 


unavailable for you to store data. 


Types of Data Files 


How to generate the various types of diskette data files is discussed 
under /nput/Output Contro/. Two types of data files can cause 
diskette file storage to be unavailable for storing data: U (unblocked) 
and M (mixed). 
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Type U Data File 


A type U data file specifies that each record in the file starts at the 
beginning of a sector and that a record cannot span from one sector 


to another. 

Data File 

a 
Individual Sectors For a type U data file, each record 


must be contained in one sector. 


The sectors on a diskette can be 128, 256, 512, or 1,024 bytes. If a 
record does not require the number of bytes available in a sector, the 
remaining portion of the sector is unavailable for data storage. 


Beginning of 256-Byte Sectors 


Data Fe i ee 

\ ee” WUD tee’ WIA 
re 
Unavailable Diskette Storage 


To obtain the maximum available storage for a type U data file, you 
should do one of the following: 


e Write records to the file that are the same size as (or as close as 
possible to) the sector size. 


e Use a diskette whose sectors are initialized (128, 256, 512, or 1,024) 
nearest to the record size. Remember, the entire record must fit in 
one sector. 


Type M Data File 


A type M data file specifies that each record in the file requires the 
same amount of file storage as the first record written to the file. That 
is, the first record determines the characteristics of the file. Any 
record written after the first record cannot be larger than the first 
record. 


Data File 
7 Peainning of the Data File 


100 Bytes 100 Bytes 100 Bytes 100 Bytes 100 Bytes ( 
\ accesses comes 


The first record used this amount of storage; 
therefore, any following records are allocated 
the same amount of file storage. 


If any of the following records do not require as much storage as the 
first record, the remaining portion of the storage allocated for the 


record is unavailable for data storage. 


Increments of 100 bytes as specified by the first 
record written to the file 


100-Byte 80-Byte Gis EG ay 100-Byte 90-Byte Y 
Record Record Y pee Record Record Z 


The first record i 
written to the file 


Unavailable Diskette Storage 


To obtain maximum available storage for a type M data file, you 
should make the records as uniform in size as possible. Remember, 
the size of the records following the first record must be equal to or 
less than the size of the first record. 
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Allocation of File Space 


Previously in this section, reallocating diskette file space using the 
)FREE and )MARK commands was discussed (see Reallocating 
Diskette File Space). Using the )FREE and )MARK commands to 
reallocate diskette file space can cause fragmented blocks of 
unallocated file space on the diskette. For example, assume a diskette 
has all the file space allocated, except the following 15K of file space 
on a cylinder: 


Diskette 
Cylinder 


10K of Unallocated BK of Unallocated 
File Space File Space 


Now, if you need that 15K of storage for a new file to be marked, the 
storage is not available because it is not in 15K continuous bytes. — 


The fragmented blocks of unallocated file space can be made available 
by the compress function (see the /BM 5110 Customer Support 
Functions Reference Manual, SA21-9311). The compress function 
closes the gaps caused by the unallocated file space and places all of 
the unallocated file space in one continuous area. 


Chapter 9. Printer Control 


You can specify what data is sent to the printer by using the )OUTSEL 
system command or an APL shared variable. Also, at any time, you 
can print all the information on the display screen by holding down the 
CMD key and pressing the key. When an APL shared variable 


is used to send data to the printer, except for using the CMD 
and key, all the data to be printed must be assigned to 
x 


the shared variable. (See /nput/Output Contro/ for more information 
on using shared variables for printing data.) The )OUTSEL command 
has three options to specify which data on the display screen is 
printed. These options are: 


e ALL-specifies that all subsequent information displayed is printed. 


e OUT-specifies that only output is printed. Even though input is 
displayed it is not printed. For example: 


var a 


8 


If you enter this statement, the statement 
is displayed but not printed. 


The output (result) from the statement is displayed 
and printed. 


e OFF-—specifies that none of the information displayed is printed, 
unless an APL shared variable is used to send the data to the 
printer. 


You can use the following system variable and APL function to specify 
the format of printed output: 


e OPP Specifies the printing precision of numeric data (how many 
digits are printed) 


e 5 OCC n Specifies the starting print position (tab n) from the left 
margin 


® * Formats numeric data into character data 
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FORMATTING OUTPUT 


You can use the [PP system variable to specify the number of digits 
to be displayed and printed for decimal numbers and for integers with 
more than 10 digits. In a clear workspace, the OPP system variable is 
set to 5 (default value). For example: 


12345. a? 


A decimal number with seven digits. 
L254 


Only five digits are displayed, and the least significant 
digit is rounded off. 


The value of OPP does not affect the internal precision of the system. 
For example: 


He Le sue, ae? 


ae ra five digits are printed. 

Less 
Lip Pe? << —— Change the printing precision to seven digits. 
A 

12305, 4647-—_““»_»¥{=»»_-_No tice that. the value o f A is st ill seven digits. 
LIP Pe 2 
fy 

1. 2k4 <~———_—————— Even though only two digits are printed, the 

internal value of A in the system is seven digits. 


Although the OPP system variable allows you to specify the number of 
significant digits printed for decimal numbers or integers with more 
than 10 digits, there might be times when even more control is needed 
for the printed output. The 7 (format) function allows you to 
specify the precision and spacing of numeric data. The F function 

also converts the numeric data to character data. This makes it easier 
to print the formatted numeric data with other character data. For 
example: . 


Numeric Value 
‘THE CLASS AVERAGE TS:.',80 “a 
nOMAIN ERROR 
"THE CLASS AVERAGE TS: ',80 You cannot join numeric 
A and character data 


"THE CLAS 
THE CLASS AVER 3: Bt 
THE CLASS ‘ ae erent 


The Printed Result 


The following examples show how the’ ¢__ function can be used to 
control spacing and precision of numeric data (see the /BM 5110 APL 
Reference Manual, SA21-9303, for a complete description of 

the function): 


Kes 2Qoel2. 34 “Su,567 0 12 7.26 “1236S 


ih 
12. 44 “SH SG? | 
(} 12 ~— Numeric Value of B 
“0,26 “4. ree So) 
Spacing of Nine Positions for Each Number 
Each number. should contain two decimal places 


+——————— Formatted Character Result 


: Spacing and Precision for the First Column 
4 pe and Precision for the Second Column 
62°99 198. 
L2, 34 “Su S 
»00 12.0. 
“26 oe ee 


———_—_——— Formatted Character Result 


Nine Positions 


Six positions 


You can use the NCC (console control) system function to specify a 
tab position from the left margin. The printed output then starts from 
that tab position. To specify the tab position, the left argument of the 
UICC function is 5 and the right argument specifies the tab position. 
For example: 


"PRINTED OUTPUT’ 7 
PRINTED QUTPUT The explicit result of 
the LICC function. 
BTCC 20 
1 
‘PRINTED OUTPUT! 
PRINTED GUTPUT 


aa aa 


20 character positions 
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FORMATTING REPORTS 


Sometimes the data stored in the 5110 cannot be used unless the data 
is in a printed report. And the printed report cannot be used unless 
the report is in a readable format. The following procedure can be 
used to generate a readable report, assuming the necessary data for 
the report is already stored in the 5110: 


1. Determine the headings for the report. The headings should 
describe the information in the report. 


2. Arrange the data so that the data will be located under the 
appropriate heading. 


3. Edit the data (see Useful APL Statements and User-Defined 
Functions for Formatting Reports). 


4. Print the data. 


The following example shows how this procedure might be used. 


Assume you have the following data stored in the system: 


PART 
S92U01 
SP 2NUO2 
S9LUOS 
SOOU OU. 
SPLQUOS 
SFQU06 
S92HO? 


NAMIE 

SCREW 

NUT 

WASHER 
CONTACT 

LE AY 

POST 

CRT 


0 


A numeric matrix with each row representing 
a part number of items in stock 


A character matrix with each row representing 
the name of the associated part number in 
matrix PART 


A numeric matrix that 


9 2 9 UFDATA 


0 ,02 10009 contains the in-stock quantity, 
0 LO 1060  on-order quantity, cost per 
“000 LO1 “000 part, and reorder quantity for 
0 50 “000 the associated part number 
O00 1.03 300 in matrix PART 
0) eats 200 
200 134.59 200 


Now, suppose you want a part inventory report that shows: 
e@ The part number and name. 

e@ The in-stock and encordee quantities. 

@ The cost per part. 


@ The reorder quantity and reorder flag. The reorder flag indicates 
that the combined in-stock and on-order quantities are less than the 
reorder quantity. 


The first step is to determine the headings for the report. In this 
example, the following heading is entered: 


4 Position 1 on Line 1 


HE AIG? S4e ‘PART QUANTITY COST REO 
ROER', ‘NUMBER NAME IN-STOCK ON-ORDER PER PART QTY FLAG’ 
The second step is to arrange the data so that it is located under the 
appropriate heading. In this example, the following statements are 
used to arrange the data: 


BOLVY¢e¢6 OFPART),' ', CC | en Join the part numbers and names 
BOUY¢BODY,8 0.9 0,12 3 6 0 ATA together. 
a ee ce ay | 


Tay 


This matrix now contains the The spacing and precision to format each | 
part number, name, in-stock associated column of the matrix DATA. 
quantity, on-order quantity, 

cost per part, and reorder 

quantity for each part on 

inventory. 
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At this point there is not enough information available to complete the 
report. The reorder flag is needed to indicate the parts with a 
combined in-stock and on-order quantity that is less than the reorder 
quantity. The following user-defined function might be used to place 
asterisks (*) in the reorder flag column when the in-stock plus 
on-order quantity is less than the reorder quantity: 


nd 
be 
n3J 
Yo 
ie 


VREORDERFLAGCHI¥ 

RF EREOQRDERFLAG; I; X 

Te COATAL;AI+0ATAL; 27) <DATALC SU 

XervCiteDATAd 

Te 1/X —<———— Selects the rows where the condition 
RFE CCitelaATaAd,S de! specified in statement 1 is true 
RFE) de ' «! 


REKKRE 


Places the reorder flag ( ) in the appropriate rows 


Now, the following statement can be used to add the reorder flag the 
report data: 


BODY¢ BODY, REQRDERFLAG 


The body of the report now looks like this: 


S9QUOL 
S92H02 
SILOS 
S92U- 04. 
SILHOS 
SP2406 
S9QH07 


BOTY 
SCREW 
NUT 
WASHE 
CONTA 
LEAT 
POST 
CRT 


1000 0 02 1000 
1000 0) 01 1000 
R 000 2000 . O01 2000 
CT 0 ) owl) 22 () OO) 2 9696 
20 700 1.03 O00 
WOO 0 are a OQ 0) 36 eH 
~O0 200 136,59 200 


The third step is to edit the data. In this example, a dollar ($) is to be 
placed before each cost per part. 


BODY. | 


S616 ' B! 


The fourth step is to print the report. This might be done several 
ways; for example: 


e@ Join the heading and the body and then print the entire report. 


REPORT¢HEAD, CLIBOLY 


e Use a user-defined function to print out the report. For example: 


ie Ee 


ee 


C3 
Up oI 
Co 
Dé 1 


y 


VREPORTC(V 


REPORT 

HE ATI 

BOUYe (4 O FPART),' °, NAME 
ROWYeHONY, 8 0 9 0 12 2 8 0 DATA 
BROWY¢ BODY, REQRDERFLAG 
BODYE ; 36]¢'$° 

BOLY 


Now, when the report is printed, it looks like this: 


REPORT 

PART QUANTITY COST 

NUMBER NAME IN-STOCK ON-ORDER PER PART 
S92H01 SCREW 1000 0 $ 02 
S92402 NUT 1000 0 $ O01 
392403 WASHER ~O000 2000 $ 02 
392404 CONTACT 0 0 $ el) 
S924U05 LEAL 20 700 } 1.03 
392406 POST 400 0 $ arte 
S92407 CRT 300 200 $ 136.59 


REORDER 
QTY FLAG 


1000 


L000 
2000 
LOO OD eK 
300 
£50) 0 96 6% 
200 
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USEFUL APL STATEMENTS AND USER-DEFINED FUNCTIONS FOR 
FORMATTING REPORTS 


Following are examples of APL statements and user-defined functions 
that might be useful for formatting reports. 


Drop Blanks from a Character Vector: 


VOROPCMIY 
Y ZeLROP x 
til Zecx#' ')/X 
v 


X¢'A BC UT E FG’ 
DROP X 
ARBCIIEFRG 


Drop Blanks and Periods from a Character Vector: 


VOROPBPLAV 
¥ Z¢NROPEP X 
| ZeCXe! . 5 SK 
v 


X¢'ALBLC To E F' 
DROPEP xX 
ARCTEF 
Replace Periods with Commas in a Character Vector: 


VREPLACELIIV 
¥V Z2¢REPLACE X 
rid ALCX#' o/s vaAXTe' 
Lae LEK 
¥ 


x 
A,B,C DT E F 
REPLACE xX 
A,B,C UE F 


Drop Leading Blanks in a Character Vector: 


VLEANINGC OAV 
¥ Z¢LEADING X 
a ZLECvaA\' =X) /% 
v 


Pye ABC DEF’ 


LEATING A 
ABC TIEF 
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Left-Justify the Names in a Matrix: 


FLICUAY 
Vi Zeid xX 
C47 LECHSANK' 5 OX 


NAMES¢3 66° SUE JAN 
NAMES 
SUE 
JAN 
DAVE 
LJ NAMES 
SUE 
JAN 
DAVE 


Find the Index of a Name in a Table: 


VINDEXCOI¥ 
¥VoZe¢NAME INDEX TABLE 


NAVE ° 


ria Z2¢ CC TABLES. = C7 1t eTABLE) TNAME) )/.1t ePTABLE 


V 
NAMES 
SUE 
JAN 
NAVE 
"JAN' INDEX NAMES 
"y 
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insert Blank Lines into a Character Matrix: 


VBLANKLINESCOI¥ 
¥oZeX BLANKLINES M 
rid ZeCCCitemMd+  CitemMd=xX)eCXel), OM 
i 


NAMES¢é6 Ye' TON TAN SUE JIM TOM KIM 
NAMES 
DON 
THAN 
SUE 
JTM 
TOM The left argument determines how 
KIM often the blank lines are inserted. 
2 BLANKLINES NAMES 
DON 
TAN 


SUL. 
JT 


TOM 
KIM 


Print a Matrix Using a Shared Variable: 


VPRINTCOAV 
VY PRINT X;2Z;P 
East CReMAVEIO+1 369 
a Pe" PRT * 
a Z2¢) (ISVQ 'P° 
iu] Pe"14,0*X),CR 


V 
NAMES¢3 Ue' SUE JAN DAVE 
NAMES 
SUE 
JAN 
DAVE 
PRINT NAMES 
SUE 
JAN 
NAVE 
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Drop Leading Blanks or More than One Consecutive Blank from a Character 
String: 


VSCANCOIAV 
Vo ZeSCAN X 
es ee Z2ELeCCxX#' Sov '4LOK/ Xe’ 8k 


At A & C Oe Ss ee 
SCAN & 
A BC Yi EF 


Convert a Scalar or Vector to a Matrix: 


VCONVERTOQIYV 

Vo ZeCONVERT X 
ria e(Q0 1 2 =eexXo/ (SCALAR, VECTOR, MATRIX) 
Ped | MATRIX: ZX 
C33 90 
CuI SCALAR: Ze 1 1 px 
aoe 30 
C61 VECTOR Ze C1, eX) ex 

¥ 


A&I. 
eA 


AGCCONVERT A 
er 
: 


Join Two Variables Together Side by Side: 


VEYCTIAY 

YoZeA BY FS ROW 
ni AeCStCpad, 1 ldeAé 
{21 Ke Cetcekd, L Liek 
C32 ROWe Lt ¢eAdT ok 
yy A& CROW, “LteAad ta 
tS 2 Be CROW, “iteBd tk 
ré] Zea, 

v 


Aes Ze A! 
Bes Bp’ BR’ 
A BY & 
AARKE 
AARBE 
BRE 


Printer Control 105 


106 


Join Two Variables Together One on Top of the Other: 


AA 
AA 
BEE 
REE 
GEE 


VONCQIV 

Z¢eA ON BF; COL 
AeC"2t 1 1 , eA PA 
Re¢"2t 1 1 , PB) ek 
COLE “1t (pA T eB 
A&C CI tpAd, ,COLITA 
BeCCiteR), COLO TE 
Z¢A,011 B 


Aea 2p' A! 
BRe3 Se'R' 
A ON & 


Chapter 10. Input/Output Control 


Input/output operations consist of the following: 

e Reading and writing data records on a tape or diskette data file 
e Reading and writing data on the display screen 

e Printing data records 


In this chapter, the following topics concerning input/output control 
are discussed: 


e Sequential and direct access data files 
e Logical and physical records 
e Types of data file formats 


e APL internal code to EBCDIC (extended binary coded decimal 
interchange code) translation 


e The 5110 I/O processor 


e Establishing an APL shared variable as the connection between the 
active workspace and the I/O processor 


e Using the APL shared variable for input/output operations 


e Retracting the shared variable offer 
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SEQUENTIAL AND DIRECT ACCESS DATA FILES 


Sequential access data files can be on tape or diskette: however, 
direct access data files can only be on diskette. The data file is 
specified as either a sequential access or direct access data file when 
it is initially created (see Specifying the Operation to be Performed 
later in this chapter). 


All 5110 data files are created sequentially: that is, individual records 
are written to the file in sequential order. 


Data File 


re 


After a data file is created, data can be read from the file as follows: 


e For a sequential access file, the records are read in the same 
sequence as the records were written to the file. For example, the 
first and second record must be read before the third record can be 
read. Also, if you want to read a record previous to the last record 
read, you must start the operation over from the beginning of the 
data file. 


e For a direct access data file, you specify the record(s) that are to be 
read from the data file. For example, you can specify that the fourth 
record in the file be read (without reading the previous three 
records) then after the fourth record is read you can specify that the 
second record in the file be read, and so on. Also, multiple records 
can be read with one statement. 


LOGICAL AND PHYSICAL RECORDS 


A logical record is the individual record written to a data file. For 
sequential access data files, the size of each logical record can vary. 
For example, one logical record might require 10 bytes of storage and 
the next logical record might require 20 bytes of storage. For direct 
access data files, each logical record requires the same amount of 
diskette storage. Generally, each logical record must be the same 
shape and representation as the other logical records in the data file. 


A physical record is a certain amount of tape or diskette storage. For 
tape, a physical record is 512 bytes. For diskette, a physical record is 
the same as the diskette sector size (128, 256, 512, or 1024 bytes). 


TYPES OF DATA FILE FORMATS 


For Sequential Access Data Files 


There are two types of data file formats for sequential access data 


files: 


e APL internal format 


e General exchange format 


Following is a description of these data file formats. 


APL Internal Format 


The APL internal format allows data to be written to the data file in 
the same format as that stored in the active workspace. For example, 
the first record written to the data file might be a numeric 10 x 20 
matrix, and the second record written to the data file might be a 
10-element character vector. 


General Exchange Format 


The general exchange data format is the basis of exchange between 
the 5110 APL and BASIC languages. The general exchange format 
only allows character scalars or vectors to be written to the data file. 
Therefore, when the system is storing numeric data in data files with 
the general exchange data format, the format function must first be 
used to change the data to a character scalar or vector. 


The following rules apply to a general exchange format data file that is 
written using the APL language for later processing using the BASIC 
language. 


1. 


All data items must be separated by commas. For example, the 
numeric vector 1 3 5 6 must be changed to character data, then 
commas must be placed in the blank positions. The following 
statement replaces blanks with commas in a character vector: 


AUCCK#' 'O/ veXTe' | where X is the character vector. 


Negative signs must be replaced by minus signs. 


The 5110 BASIC language accepts only the first 255 characters in 
each character constant. 


The 5110 BASIC language creates a logical record for each PUT 
statement or each row of an array with a MAT PUT statement. 


Input/Output Control 


109 


110 


When the 5110 APL language is used to read a general exchange 
format data file (see 7o Read a Sequential Access Data File \ater in 
this chapter), the following actions are taken by the 5110 if a cursor 
return character (hex 9C) or end-of-block character (hex FF) was 
embedded in a character vector that was written to the data file: 


if a cursor return character was embedded in the character vector, 
the data will be read from tape in a different sequence than it was 
written to tape. This condition occurs because as the interchange 
data is written to tape, the system writes an end-of-record 
character (hex 9C) after each character vector (record) that was 
written to tape. The end-of-record character and the cursor return 
character are the same. When used on tape, this character 
separates the data (records) so that it can be read from tape in the 
same sequence as it was written to tape. However, if a cursor 
return character is embedded in the data that was written to tape, 
the system will recognize it as an end-of-record character when the 
data is read from tape. 


If an end-of-block character was embedded in the character vector, 
any data from the embedded end-of-block character to the next 
physical record is not read from tape. This condition occurs 
because the system looks at the tape in 512-byte segments (one 
physical record). A physical record can be terminated by an 
end-of-block character (hex FF). When the system is reading data 
from the tape and an end-of-block character is encountered, the 
system skips to the next physical record and continues reading data. 
Therefore, if an hex FF character is embedded in the data that was 
written to tape, the system recognizes it as an end-of-block 
character when the data is read from tape and skips ahead to the 
next physical record. 


For Direct Access Data Files 


There are five types of data file formats for direct access data files. 
These formats are: 


APL internal format 

General exchange format 
Unblocked and unspanned format 
Mixed format 


Nontranslated format 


Following is a description of these data file formats. 


APL Internal Format 


The APL internal format allows data to be written to the data file in 
the same format as that stored in the active workspace. However, 
unlike sequential access data files, all the records written to the data 
file must have the same shape and internal representation. For 
example, all of the records written to the data file must be one of the 
following: 


e Character data 

e Numeric binary data (all zeros and ones) 

e Numeric fixed point (all integers in the range -23' to 231-1) 
e Numeric floating point (all other values) 


These records must have the same shape and representation because, 
when multiple records are read from a direct access data file, the 
records are laminated (joined) together along a new first dimension 
(see Updating a Direct Access Data File \ater in this chapter). 


General Exchange Format 


The general exchange format for direct access data files is similar to 
the general exchange format for sequential access data files (see For 
Sequential Access Data Files under Types of Data File Formats in this 
chapter). However, when the general exchange format is used with 
direct access data files, all the records written to the data file must be 
character data and must have the same shape (po DATA) as the first 
record written to the data file. The records must have the same shape 
because, when multiple records are read from a direct access data file, 
the records are laminated together along a new first dimension. 
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Unblocked and Unspanned Format 


The unblocked and unspanned format is the basis for general 
exchange with other products using diskette storage. In this case, the 
file name cannot exceed 8 alphameric characters, and the diskette 
sector size must be 128 or 256 bytes. 


The unblocked unspanned format allows only character scalars or 
vectors to be written to the data file, with each record starting on a 
sector boundary. Also, the records cannot exceed (span) a sector 
boundary. 


Sector Boundaries 
x 


bt ar 


The records cannot exceed sector boundaries 


When the unblocked and unspanned format is used, all the records 
written to the data file must have the same shape (9 DATA) as the 
first record written to the data file. The records must have the same 
shape because, when multiple records are read from a direct access 
data file, the records are laminated together along a new first 
dimension. 


Since the unblocked unspanned format requires each record to start 
on a sector boundary, to prevent wasted diskette storage the record 
size should be as close as possible to the sector size. The unused 
diskette storage in each sector is unavailable for storing data (see 
Type U Data File in Chapter 8, Diskette Concepts). 


Mixed Format 


The mixed format, like the APL internal format, allows data to be 
written to the data file in the same format as the data is stored in the 
active workspace. However, the mixed format also allows you to 
write records that have different internal representations on the same 
data file. For example, you can write character data, logical data, 
numeric fixed-point data, and numeric floating-point data on the same 
data file. With the mixed format, the first record written to the data 
file determines how much file storage is allocated for each additional 
record to be written to the data file. For example: 


18t Record eam 
100 Bytes _ 100 Bytes 100 Bytes 100 Bytes 102 Bytes ( 


If the first record requires 100 bytes of file storage, 100 bytes of 
storage are allocated for each additional record. See Storage 


Requirements in the 5770 APL Reference Manual for information on 
how many bytes of storage are required for each data type. 


As various size records are written to a mixed format data file, any 
unused diskette storage allocated for each record is unavailable for 
storing data (see 7ype M Data File in Chapter 8, Diskette Concepts). 


Because the records in a mixed format data file do not have to be the 
same shape or internal representation, only one record at a time can 
be directly accessed from the data file. That is, multiple records 
cannot be laminated together. 
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Nontranslated Format 


The nontranslated format is used primarily for reading diskettes from a 
non-5110 system and the diskette does not have standard 5110 file 
types. Therefore, unless you need to read diskettes that do not have 
standard 5110 file types, you might want to skip this topic. 


The nontranslated format is the only format that is not specified when 
the data file is initially created. The nontranslated format can be 
specified only when the system is reading from or writing to any 
diskette data file that already exists. When data is written to a direct 
access data file using the general exchange or unblocked unspanned 
format, the APL internal code is translated to EBCDIC code before the 
data is written on the diskette. This EBCDIC code is then translated 
back into the APL internal code when the data is read back into the 
active workspace. 


APL Internal Code 1 —— Code - 


APL Internal Code aba i Code ; 


Active Workspace Translation Diskette Storage 
Tables 


However, when the nontranslate format is specified, all attributes of 
the file are ignored and any existing diskette file can be read from or 
written to. In this case, as the data is being read from or written to 
the file, the data is not translated from the EBCDIC or APL internal 
code to the other code. 


Instead, as data is being read in the nontranslate format from an 
EBCDIC diskette file, the EBCDIC representation of the data is placed 
in the active workspace. Or when data is being written in the 
nontranslate format to the diskette file, the APL internal representation 
of the data is written to the diskette file. 


Note: Assuming UIO is 0, the APL internal representation of a 
character is equivalent to the hexadecimal value of that character's 
index in the atomic vector. For example, the APL internal 
representation of the character A (DAV [86]) is hex 56 (the bit value is 
01010110). You can determine the bit value of the atomic vector index 
using the encode (tT) function. For example: 


22222222 1 8 


doce fee ee aes dive 


104 0 dt a) 
ee 56 


The EBCDIC character A has a hexadecimal value of C1 or a decimal 
value of 193. In non-translate mode (and 01O0<1), when the EBCDIC 
character A is read from a diskette, the character is stored internally 
and displayed as a lowercase h (DAV [193)). 


The nontranslate format allows only character vectors to be written to 
the file. Also, each sector on the diskette is considered one record. 
Therefore, if you specify that three records should be read or written, 
you will read or write three sectors on the file. 


Sector Boundaries 


tt Fa 


 csennntimmmenmeenemmnemmmeneeemenneetne eee ee 


When nontranslate format is used, 
three records are equa! to three sectors. 
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THE 5110 1/O PROCESSOR AND SHARED VARIABLES 


The 5110 I/O processor is responsible for transferring data from the 
active workspace to the tape, the diskette, the display screen, or the 
printer, and for transferring data from the tape, the diskette, or the 
display screen to the active workspace. Before individual data records 
can be transferred by the I/O processor, a shared variable must be 
established as the connection between the active workspace and the 
1/O processor. That is, the variable is shared between the active 
workspace and the I/O processor. 


Once this connection is established, the shared variable is used to 
send control information and data to the I/O processor and to receive 
return codes and data from the I/O processor. 


ESTABLISHING AN APL SHARED VARIABLE 


A variable must be offered to the I/O processor before the variable 
can become a shared variable. To do this, you must use the DSVO 
(shared variable offer) system function. The OSVO function requires 
two arguments; the left argument must be 1 (to specify the 5110 1/0 
processor), and the right argument must be character data that 
represents the variable name(s) to be shared. If more than one name 
is required, the names may be entered as a character matrix with each 
row representing an individual name. For example: 


1 GSVv0 ‘A' ————__—__The variable name A is 
offered to be shared. 


1 SV0O 3 le‘ Age’ 


The variable names A, B, and C are 
offered to be shared. 


The OSVO function generates an explicit result of 2 for each variable 
name that is successfully established as a shared variable with the 1/O 
processor. For example: 


X¢i (SVO 3 ie ABC’ 
x 
2 2 2 
era are two users of the shared variable, the 
active workspace and the !/O processor. This is called 
the degree of coupling. 


A 0 or 1 is the result of the OSVO function for each variable name that 
is not successfully shared with the I/O processor. If the result is 1, 
the left argument of the OSVO function was a value other than 1. In 
this case, the variable name must be retracted and offered as a shared 
variable again with a 1 as the left argument of the DSVO function 
(retracting the shared variable name is discussed later in this chapter). 
If the result is 0, an error message is also displayed. 


You can establish up to 12 shared variables in the 5110 active 
workspace. If you attempt to establish more than 12 variable names 

as shared variables, the error message INTERFACE QUOTA 
EXHAUSTED is displayed. The statement (0#[]SVO [INL 2)°fINL 2 
displays the existing shared variable names in the active workspace. If 
12 shared variable names are already established, you must retract a 
shared variable name before another variable name can be offered. 
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USING APL SHARED VARIABLES 
Once a shared variable is established as the connection between the 
active workspace and the I/O processor, you can do the following 
input and output operations: 
e Create a new sequential access or direct access data file. 
e Add data to an existing data file. 
e Read data from a sequential access data file. 
Read-only data from a direct access data file. 
@ Update (read and write) data in a direct access data file. 
e Read data from and write data to the display screen. 
© Send data to the printer. 
The first value assigned to the shared variable must be a character 
string (enclosed in single quotes) that specifies the operation to be 


performed. Specifying the operations to be performed and doing 
input/output operations are discussed next. 


To Create a New Sequential Access or Direct Access Data File 


The first value assigned to the shared variable must specify the 
operation to be performed as follows: 


OUT A 
SV< ‘OUTF  device/filenumber {D= (file 1D) MSG = OFF TYPE =|" 
" U 
Type of data file: M 
@ OUT — Sequential access 
@ OUTF — Direct access Type of data file format: 
@ A —APL internal 
@ |! — General exchange 
Direct access @ U — Unblocked/unspanned 
files only @ M — Mixed 


For example: 
SVe¢'QUTF 11003 If=(SALES) MSG@OFF TYPE=t' 


Unblocked and unspanned 
data file format. 


The error messages are not displayed. 
The data file identification is SALES. 
Diskette drive 1, file 3. 


Create a direct access data file. 


(See the /BM 5110 APL Reference Manual for a detailed description of 
each parameter.) 
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Once the operation to be performed is specified to the |/O processor, 
the I/O processor assigns a return code to the shared variable. For 
example: 


Sye'OUTFE 11003 ITl#(SALES) MSG=O0FF TYPE=U" 


ot : : 
SM The return code is checked by referencing the 


0 0 en shared variable. 


The return code is a two-element vector. 


In the previous example, the return code is 0 0, which indicates that 
the operation to be performed is successfully specified to the |/O 
processor. See the /BM 5710 APL Reference Manual for a description 
of all the return codes. 


Once the operation to be performed is successfully specified, the 
shared variable used to specify the operation is then used to specify 
data that is to be written on the data file. That is, each time new data 
is assigned to the shared variable, the 1/O processor transfers that 
data to a data file and assigns a return code to the shared variable. 
For example: 


SYedq2@¢ RECORD ONE' Remember, in this example, the 
SV data file format is unblocked and 

0 0 unspanned. All of the records in the 
SVeLet RECORD TWO" data file must have the same shape. 
$V 


SY <_< _________——_———_—_— Notice that the shared variable 
TO STATUS: INVALID. OPERATION cannot be referenced more than 
INTERRUPT once to check the return code. 

SV 

A 

SVeL2¢ RECORD THREE’ 

Ke SV 

x 


0 O- 
Le The return code can be assigned to another 
0 06 variable and then checked more than once. 


120 


When all of the data is.written to the data file, the operation must be 
terminated. The operation can be terminated by assigning an empty 
vector to the shared variable. For example: 


SV. + Empty vector 
SV 
0 0 = The operation is terminated. The variable 
SV is still shared with the !/O processor. 
Therefore, SV can be used to specify and 
perform another input/output operation. 


See the /BM 5110 APL Reference Manual for a description of other 
ways to terminate the operation. 


To Add Data to an Existing Data File 


There will be times when you want to add data to an existing data file. 
If you specify an OUT or OUTF operation, the data you write to the 
file always starts at the beginning of the file and the new data is 
written over any existing data. Therefore, to add data to a data file 
starting after the last record in the file, you must specify the operation 
to be performed as follows: 


SV < ‘ADD [device/file number] [ID = (file ID)] [MSG = OFF]' 


For example: 


SVé ADD 11003 Ite (SALES) MSG=OFF' 
SV 


Do not display the error messages. 


The file identification of the existing data file. 
The data file is on diskette drive1, file 3. 


Add data starting after the last record in the data file. 


Even though the device/file number and ID = (file ID) parameters are 
optional, one or the other of these parameters must always be 
specified. 
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The type of data file (sequential access or direct access) and data file 
format are determined by the attributes of the existing data file. In this 
case, assume this example is continued from the previous topic, the 
file is a direct access, unblocked, and unspanned data file. 


Once operation is specified, data can be sequentially written to the 
data file. For example: 


SVe_et' RECORD FOUR’ 


Sv 
0 0 
SVeLet' RECORD FIVE’ 
$V 
0 0 
SV¥ea d You can terminate the operation 
SV by assigning an empty vector to the 
0 0 shared variable. 


To Read a Sequential Access Data File 
Once a sequential access file is created, the records are sequentially 
read from the data file. That is, the records are read from the data file 


in the same sequence as the records were written to the data file. 
You specify the operation to be performed as follows: 


SV+ ‘IN [device/file number] [ID = (file ID)] [MSG = OFF]’ 


For example: 


SVe'IN 11004 Tte(SEQ) MSG=OFF 
SV 


Do not display the error messages. 
The existing data file identification. 
The data file is on diskette drive 1, file 4. 


Read data from a sequential access data file. 
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rs 


t 
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After the operation is specified, the |/O processor assigns a return 
code to the shared variable. The |/O processor then assigns a new 
record from the data file to the shared variable each time the shared 
variable is referenced. For example: First, to create a sequential 
access file with 5 records. 


1 SVoO 'sy' 


VSEQUENTIALC OI 

SEQUENT TAL 

SVe "QUT 11008 Ine(SEQ) TYPE=,A' 
Le 1. 

LOOP: 3¢v/0XeSV)/ERROR 
SVe'RECORE ', +1 
eCSeTeL+1)/L00P 
SVE 
CASO XESGVI/O 

ERROR: CREATING THE DATA FILE FAILED. THE RETURN COME tS: 

"4X 


<i 


y 


SEQUENT TIAL 


Now, to read the 5 records from the data file. 


SVe'IN Tl (SEQ) ' 


$v=—-—_—____——————. You should check the return code after the 


0 0 operation is specified. 
SV 

RECORD i 2 After the return code is checked, each time 
SV the shared variable is referenced, the 1/O 

RECORD 2 processor assigns the next record from the 
SY data file to the shared variable. 


RECORD 3 


X¢ SV +~—____—__—_______ If you want to save a record for later use, you 


x must assign the shared variable to another variable. 
RECORE Y. 

SV 
RECORD & After the last record is read from the file, an empty 

si a vector (sO) is assigned to the shared variable. This 

ae empty vector terminates the operation. (Ina 

SV user-defined function, you can check for the 

00 . empty vector. For example: > (0 = pX < SV)/DONE. 


The statement branches to DONE if the last record 
read was an empty vector.) 
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When reading a sequential access data file, the |/O processor does 
not assign return codes to the shared variable. However, if an error 
occurs, an empty vector is assigned to the shared variable and the 
operation is terminated. Then the \/O processor assigns a return code 
to the shared variable that indicates why the error occurred. 


You can also terminate the operation at any time by assigning an 
empty vector to the shared variable. For example: 


GVe'IN Ile (SEQ) ° 
GV 
i 0 
SV 
RECORD 1 
SV 
RECORD 2 


es read operation is terminated. 
cy 
SV 


To Update Data in a Direct Access Data File 


Once a direct access data file is created, specified records in the data 
file can be updated. That is, records can be read from the data file, 
updated in the active workspace, and then written back to the data file 
at a specified record location. Unlike the operations discussed so far, 
reading or writing specified records on a direct access data file 
requires a pair of shared variables. One of the shared variables is 
used to specify control information to the I/O processor. The I/O 
processor also assigns the return codes to this shared variable. The 
other shared variable is used for data that is written to or received 
from the data file. The pair of shared variable names must have the 
following characteristics: 


@ The shared variable name used to specify the control information 
must have the 3-character prefix CTL. 


e The shared variable name used for the data must have the 
3-character prefix DAT. 


e After the 3-character prefix, the next 15 characters in each name 
must be identical, if specified. For example: 


CTL These variable names can be used as 
DAT : : 
a pair of shared variables. 
or 
CTL NAM | 


DAT NAME 


Once the pair of shared variables is established, you specify the 
operation to be performed as follows: 


CTL< ‘IOR [device/file number] [ID = (file ID)] [MSG = OFF] [TYPE = N]’ 


IORH 
If this parameter is 
specified, the data is 
Read or write to.a not translated (see 
direct access data file. Nontranslated Format). 
See the /BM 5110 APL The other formats cannot be 
Reference Manual for ; specified when you are 
a description of the reading from or writing to a 
differences between an direct access data file, because 
1OR and IORH operation. these formats were established 


when the file was created. 


For example: 


CTLe' TOR 11005 Te (OLRECT) MSG=OFE: 
CTL 


Do not display the error messages. 
The file identification. 
The data is on diskette drive 1, file 5. 
Read records from or write records to a direct access data file. 


For a read or write operation to a direct access data file, the second 
element of the return code identifies the number of records in the data file. 
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After the operation is specified, the CTL shared variable is then used 
to specify what records to read or write. To do this, you must assign 
a two- or three-element vector to the CTL shared variable, as follows: 


0 
CTL< 1 starting record number [number of records] 
2 
ZL, on. a read records operation. If the third element 
1 specifies a write records operation. is not specified, one 
2 specifies a search by key operation. record is assumed. 


(search by key is discussed | 
later in this section). 


For example: 


CTL¢0 & 3 
wctneg three consecutive records, starting with 
the sixth record in the file. 


Note: The record numbering starts with zero. 


Therefore, the first record in the file is record number 0, the second is 
record number 1, and so on. Also, you cannot read from or write to a 
record position that was not originally created using an OUTF or ADD 
operation. 


When the CTL shared variable specifies a read records operation, the 
1/O processor assigns the records read from the data file to the DAT 
shared variable. When the CTL shared variable specifies a write 
records operation, the data currently assigned to the DAT shared 
variable is written to the data file. Therefore, the data must be 
assigned to the DAT shared variable before you specify the write 
operation. In each case, after reading or writing records, the 1/O 
processor assigns a return code to the CTL shared variable. 
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When you read multiple records from a direct access data file, the 
records are laminated together along a new first dimension before 
they are assigned to the DAT shared variable. For example, assume 
you read three records (character vectors) from the following data file: 


DATA 
FILE 
0 1 2 3 4 


ABCEF GHIJK DAN.. DAVE. JERRY Em 


CTLed 2 3 
CTL 

0 0 
DAT 

DAN, . 

DAVE, 

JERRY 


AT 
35 ec ee eee The shared variable DAT contains 


a3 x 5 character matrix. 


The new first dimension represents the number of records read. You 
can specify each individual record by indexing the new dimension. 


WATCL:3 
TIAN. . 

DATES: 4 
JERRY 


Input/Output Control 


5 


127 


128 


When you write multiple records to a direct access data file, the 
records must be joined along a new first dimension before they are 
assigned to the DAT shared variable. For example, assume you want 
to write the following three records (character vectors) to a direct 
access data file: 


VaATes Se ' AAAAABBRBECCCCC ' 
LAT Neen meee ‘ema, ammo Wegmans per” 


AAAAA Bae ae Individual Records 
BREE 


COCO 


0 1 2 3 4 
ABCEF GHIJK AAAAA BBBBB CCCCC aa 


Following is an example of updating records in a direct access data 


file: 


a 
C27) 
CSc 
CU oI 
Col 
C67 
Cel 
CSc 
Coo 


1 YSV0 2 Ye CTLXDATX ‘«~————— Establish a pair of 
shared variables. 


trae ee Create a direct access data file. 
CTLX€' OUTF 110 04 Tt=(QTRECT) TYPE=1' 

ea PRET RELERBOR CTLA and DATA can be 
LOOP I CTLX¢ RECORD ', +1 used for any input/output 
+CO#ITX¢CTLXD/ERROR ORerevOn: 

Dey eer operation is terminated; 


eats ee now CTLA can be used for other 
ae enon sparatcne. 


[ida ERROR: ‘CREATING THE DATA FILE FAILED, ' 
Clid ‘THE RETURN CODE 4S: *, +x 
¥ 


QIRECT 
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The data file now looks like this: 


0 1 2 3 4 
RECORD 1 RECORD 2 RECORD 3 RECORD 4 RECORD 5 


CTLXe' TOR 11004 Tbe (DIRECT) ' 
CTLX 
) > When you specify the operation to a direct 
access data file, the second element of 


CTLX¢d 0 the return code is the number of 
CTLX records in the file. 

0 0 
ATX Data records can be 

RECORD 4 read, 


updated, and 
DATX¢ "RECORD A eee written back at the same record location. 
CTLXeL 0 


CTLX i) 1 2 3 4 
00 


CTLX¢O 1 2 


CTLX 
0 0 Data records can be moved from 
ATX one record location to another 
RECORD 2 record location. 


RECORI! 3 
“CTLX¢l 3 2 


) 1 2 3 4 
CTLY RECORDA | RECORD 2 RECORD2 | RECORD3 


0 0 
UATX¢ ''NEW TATA! New records can replace existing records 
CTLXe1 2 in the data file. 
aa CTLX P ; j 4 F 
CTLXe 10 
CTLX Remember, when you write records to the 
0 oO data file, the records must meet the 


requirements of the data file. 


Terminate the operation. Now CTLX and 
DATX can be used for other input/output 
operations. 
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To Search by Key a Direct Access Data File 


When doing update operations to a direct access data file, you can 
search the file for a specific record by first assigning a key value to 
the DAT shared variable and then assigning the following vector to the 
CTL shared variable: 


CTL< 2 © starting record number of records 


Unlike reading from and writing to 
a direct access data file, the third 
Specifies a search element must be specified for 
by key. a search by key. 


When a search by key is specified, the key value currently assigned to 
DAT is checked against the equivalent number of beginning bytes in 
the specified sectors. The specified sectors include the sector that 
contains the starting record number through the sector that contains 
the last record specified (determined by the number of records 
specified). For example: 


Sector Boundaries 


eso] nna sa] nes [rvs] eve [war[Rvo] woh 


NATe  1Te3h' The first 4 bytes in three sectors 
OTLe2 G are compared with the key value. 


When you are creating a file for search by key operations, the file 
should meet the following requirements: 


e The records are sorted in ascending sequence. 


e The records do not span sector boundaries. However, there can be 
multiple records in a sector. 


e A record that is greater than any key value that might be specified 


should start on the sector boundary following the last valid data 
record. 
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See the /BM 5110 APL Reference Manual for a description of when a 
search by key is complete. If the search is successful, the record(s) in 
the sector containing the appropriate record is assigned to the DAT 
shared variable (multiple records are laminated together along a new 
first dimension). Also, the second element of the return code assigned 
to the CTL shared variable represents the record number of the first 
record assigned to the DAT shared variable. 


CTL. 
0 4 


NG ee search was successful, and the first record assigned 
to DAT is record number 4. 


To Read-Only Data from a Direct Access Data File 


To read-only data from a direct access data file is the same as reading 
records when updating data in a direct access data file. However, 
when you specify a read-only operation, you cannot write data back to 
the data file (a CTL DOMAIN ERROR is generated); this prevents data 
from accidently being written to the data file. You specify the 
read-only operation as follows: 


CTL < ‘INR [device/file number] [1D = (file 1D)] [MSG = OFF] [TYPE = N]‘ 


Read-only data from 
a direct access data file. 
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For example: 


CTLe INR 11005 [n= (OTRECT) MSGeOFF' 
CTL. 


Do not display the error messages. 
The file identification. 
The data is on diskette drive 1, file 5. 
Read-only data from a direct access data file. 
The second element of the return code identifies the number of 


records in the data file. 


See To Update a Direct Access Data File for a description of how 
records are read from a direct access data file. 


To Read Data from and Write Data to the Display Screen 


Reading and writing data on the display screen is similar to reading 
and writing data on a direct access data file. That is, the operation 
requires a pair of shared variables, with one of the shared variables 
having the prefix CTL and the other having the prefix DAT. You 
specify the operation as follows: 


CThé “OTSPLAY CMSGOFF I 


The error messages are not displayed. 
Read or write data on the display screen. 


A pair of shared variables is used for reading and writing 
data to the display screen. 


Once the operation is specified, the CTL shared variable is used to 
specify what character positions to read or write. To do this you must 
assign a two- or three-element vector to the CTL shared variable, as 
follows: 


CTL< 0 _ starting character number [number of characters] 


1 
If this element is not 
0 specifies a read data operation. specified, one character 
1 specifies a write data operation. is assumed. 


Input/Output Control 133 


134 


Note: Each character position on the display screen is considered one 
record. The character positions are numbered as follows: 


LINE 


15 
14 
13 
12 
11 
10 


co 


Om NWAAHDN C 


For example: 


CTLe 0 20 10+————— Read 10 characters starting 
with character position 20. 


When the CTL shared variable specifies that characters be read, the 
cursor appears on the display screen at.the character position 
specified by the starting character number. You can then modify the 
information on the display screen for the specified number of 
character positions. Also, the insert, delete, and ATTN key perform 
the same functions within the specified number of character positions 
as they do during standard APL keyboard input. Then, when the 
EXECUTE key is pressed, the specified characters are read from the 
display screen and assigned to the DAT shared variable as a character 
vector. 


When the CTL shared variable specifies that characters be written, the 
data currently assigned to the DAT shared variable is written to the 
specified positions on the display screen. DAT must be a character 
vector with at least as many characters as specified by the CTL shared 
variable. 


In each case, after reading or writing records on the display screen, 
the |/O processor assigns a return code to the CTL shared variable. 


Following is an example of reading and writing data on the display 


screen. 


1 Q5V0 2 Ye CTLOTSPRHATOISP’ 


oe 
CTLEISPe DISPLAY’ 
CTLGISP 
0 0 
CTLUTSPeO 6 Gu The cursor appears on line 14. 
CTLOTSP 
0 0 eset Now, enter DISPLAY 
is EVATRISP I/O and press 
ey hf 


YISPLAY 1/70 


EXECUTE. 
DVATOLSP 


VATHISP? LOS pHATIISP After the data is assigned to 
the DAT shared variable, the 
DAT shared variable can be used 


like any other variable. 


CTLYISPed O L024 


Write the value currently assigned 
to DAT on the display screen. 
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The display screen now looks like this: 


QYISPLAY 1/0 
QISPLAY 1/0 
QISPLAY 170 
QLSPLAayY 1/0 
QYISPLAY 1/70 
QNISPLAY 1/0 
QISPLAY 1/0 
VISPLAY 1/0 
NISPLAY 1/0 
NISPLAY 7/0 
DISPLAY 170 
VISPLAY 170 
QISPLAY 170 
QISPLAY 170 
DISPLAY 1/70 
YISPLAY I/0 


Now, scroll up 2 lines 
and enter 


CTLOLS Pe 10 
YI 


2 TLE SP 


to terminate the operation. 
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To Send Data to the Printer 


You can control what information is printed by using an APL shared 
variable. You specify the operation as follows: 


SV+ ‘PRT [MSG = OFF]’ 
4 . 
The shared variable is used for printing data. 


For example (assume SV is already established as a shared variable): 


SVG PRT MSG=QFF* 
SV 
0 0 


Once the operation is specified, only the information (a character 
scalar or vector) assigned to the shared variable is printed. The I/O 
processor assigns a return code to the shared variable after each print 
operation. For example: 


SVE ONLY THE DATA ASSIGNED 


SV 

0 0 
SVe'TO THE SHARED VARIABLE IS PRINTED! 
SV 

0 0 


When using a shared variable for print operations, you can only assign 
character scalars or vectors to the shared variable. However, you can 
also print a matrix as follows: 


MATRIXG¢ Be L2Susé 7s ' 
MATRIX 


12 
4 : Carriage return character (assuming L110<-1). 
wl CY 
= cies a This expression catenates a carriage 
. R at AN L : ae a gee a return character at the end of each 
ae Lid. CeMATRI: 1, CHMATRIXD CG uy row of the matrix and then ravels 
0 0 ov the matrix into a vector, as follows: 
oVewd 12CR34CR56CR78 YR < The last 
SV CR is dropped. 
0 0 


Now, when the vector is printed, 

a new line is started each time 
Terminate the the carriage return is encountered, 
operation. as follows: 


12 
34 
56 
78 
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TERMINATING THE OPERATION AND RETRACTING THE SHARED 
VARIABLE OFFER 


As discussed previously, you can terminate an input/output operation 
by assigning an empty vector to the appropriate shared variable. After 
you terminate the operation, the 1/O processor assigns a return code 
to the shared variable, and then the shared variable can be used to 
specify another input/output operation. 


See the /BM 5110 APL Reference Manual for more information on 
assigning an empty vector to the shared variable. 


There are four other ways that you can terminate the operation: 
e Use the OSVR system function to retract the shared variable offer. 
e Use the DEX system function to expunge the shared variable name. 


o Complete execution of a user-defined function in which the shared 
variable is made local to that function. 


o Use the )JERASE system command to erase the shared variable 
name. 


In each case, the operation is terminated and the shared variable offer 
is retracted. However, a return code is not assigned to the shared 
variable to indicate whether or not the operation was terminated 
successfully. 


Generally, the OSVR function is used after the operation is terminated 
and the shared variable is no longer required for any input/output 
operations. The OSVR system function requires one argument; this 
argument must be character data that represents the shared variable 
names being retracted. If more than one name is required, the names 
may be entered as a character matrix with each row representing an 
individual name. For example: 


{iSvRo' a! ————————_ The variable name A is no 
longer a shared variable. 
fISVR 3 le‘ ABC’ 
The variable names A, B, and C are no 
longer shared variables. 


The OSVR function generates an explicit result of 2 for each shared 
variable offer with the |/O processor that is successfully retracted. For 
example: 


X¢fISVR & Le’ ARC’ +——— In this case A, B, and C 
x are shared variables. 
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TYPE:: 
Parameter and 
Data Format 


A 


APL internal 
blocked/spanned 


Character data 
blocked/spanned 


Once the DSVR function is used to retract a shared variable offer, the 
shared variable becomes an ordinary variable. 


Ae Sey 
A 


The following chart summarizes the data file types for input/output 
operations. Sequentially accessed data files require one shared 
variable, and directly accessed data files require a pair of shared 
variables (CTL/DAT). Records in the data files can be blocked and 
spanned or unblocked and unspanned. Blocked and spanned records 
can span sector boundaries. Unblocked and unspanned records cannot 
span sector boundaries; that is, the record must be less than or equal 
to the sector size and there is only one record per sector. 


File Type 
Displayed Using 
the )LIB Command 


Sequential Direct. 
(OUT) (OUTF) |Comments 


The 5110 defaults to TYPE=A if the parameter is not 
specified. 

For file type 10, all the records in the file must be the same 
size and representation (character, binary, fixed point, or | 
floating point). : 


File types 2 and 9 can be read sequentially using an IN 
operation. 

File type 9 (blocked and spanned) uses less storage than 
file type 10 for character data. 

For file type 9, all the records in the file must be the same 
size. 


U 


Character data 
unblocked/ 
unspanned 


File types 9 and B9 can be read sequentially using an IN 
operation. 
File type BY is the basis of exchange with other products. 
__All the records in the file must be the same size. 


M 


APL internal 
blocked/spanned 


For file type 15, all the records in the file must use the 
same or less storage than the first record written to the file, 
and records must be read or written one at a time. 
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SAMPLE INPUT/OUTPUT OPERATIONS 


** SEQUENTIAL I/O x 


Sequential files on diskette are essentially the same 
as tape files, The two types are: 

GENERAL EXCHANGE (File type 2) 

APL INTERNAL (File type &) 


Sequential files require only one shared variable, 


1 TSV0 “SEQUSK ' 


2 


This example specifies ‘OUT' to indicate output 
and defaults to the APL INTERNAL File Type, 


SEQUSKe ‘OUT L1iGOL Tie CTEST)' 
Qnee the operation is established and checked 
for valid completion with a ‘0 O° return code, 
SE GUSK 
records may be written to the diskette file. 
An integer record is written first. 
SEQUSK e110 


Always check the return code on output, 
SEQISK . 


APL INTERNAL sequential files permit writing of 
any type of data within the same file. For 
example, you can write a floating point record, 
SEQUSKe . S110 
SEOQUSK 
and a binary record, 
SEQUSKe TLSe0 1 O 1 0 1 1 
SEQISK 
and a character record, 
SEQUSKe This is the LAST record.’ 


SE GUIS 


You can mow cloge the file, 
SEQUSK & 10 


SEGUIESK 
0 0 


and read what was written to the diskette. 


NOTE that only the It Cor DTevice/File Number) i¢ 
needed to specify a data file on the diskette. 


SEQUSKe IN Tle (TEST)! 
Check the return code, 
SE GIS K 
and read each record in the order that tt 
was written, 
Firet, the integer record, 
SE QS HK 
12 34 S$ 6 7 8 Y 10 
the floating point record, 
SEGUISK 
is ee eB te Se ee oa ee eo oe 
the binary record, 
SEIS K 
0Oo402 032 20642 0241 09 2 ~=«0 
and, finally, the character record. 
SE GTS kK 


This is the LAST record, 


There will now be an empty vector returned, 
which indicates the end of data or an I/0 error, 


SEGUSK 
Check for an error conditton. 
SEQUSK 


& ‘O GO ‘ return code indicates that tiuere 
is mo more data. 
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GENERAL EXCHANGE (File type 2) files are handled 
the same as APL INTERNAL files except that all data 
must be in character format, This type of file may 
be exchanged with the BASIC Language, 


Both GENERAL EXCHANGE and APL INTERNAL format 
files may be written to tape in a similar fashion 
and both are compatible with the TERM S100a, 


In addition, The S110 will read Si00 file types 1 
and 3. 


%% RECORI 1/0 3 
1 CS¥O ‘CTLIGK' 
1 TSVO ‘“DATISK' 


Two shared variables are offered which can he 
used together for record input/output. 
CTLISKe ‘OUTF 11004 [te (TEST)! 
—CTLOSK 
Assignments to CTLUSK write records onto the diskette, 


The records must all be the same length and internal 
representation since these are default TYPE=4 records, 


CTLUSKE LOA AS 
CTLOSKe LOO eB! 
CTLISKe LO0e' C* 
CTLUSKe LO0e° Ti 
CTLISKE LONE! 


CTLUSKeLOde' F' 


CTLUSKe 20e'°G' 
TO STATUS: INVALID DATA TYPE 


CTLOSKe LO&Qe HH! 
IQ STATUS: INVALID DATA TYPE 


CYLUSKe 100 e1 
TO STATUS: INVALIU OATA TYPE 


NOTE that the assignment must 
length must be 100 since that 


record, The error messages 


the MSG=OFF parameter 


was nat 


were 


be character and the 


is true with the first 
displayed because 


specified. 
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CTLUISK 10 


TLUSK 


The output operation is mow terminated, 


Normatly, you would want to check return codes 
to assure proper operation. For example, iIfROOQE 
should always be QO with record input/output 


CTLUGSKEe “LOR L100) Tle (TEST) ' 


The file is now being specified for input or output 
operations, 


You could have used INRenn- to REATIH ONLY 
or TORK to REA or WRITE, 


TOR and LORH differ in storage reauirements and 
performance, They are the same in function, 


CTLUSK 
i 4 
NOTE that there are & records available, 
All reads and writes must address one of these 
actual records, 


To add records to a record I/0 file originally 
created using QUTF, you must specify an Ait 
operation, 


CTLOISK will now be used to read and write and 
QATTSK is the variable cantaining the data, 


CTLUSKeA BC 
t t t NUMBER OF RECORDS TO READ OR WRITE 
.% FIRST RECORD TO READ OR WRITE 


CTLISKeO 0 
This gaye to read the first record CRECORD 0) and 
read only one record which is the default for 
the number of records 


eNATISK 
100 


AAAAK 


4 100 
REEE 
COCC 
LUT 


4& 100 


AAA 
Ya Ea 


COC 


0 0 


QATOSK OL 


CTLUSK ¢ 0 


You have 


ePNATIISK 


DATOSKE | 1 


QATISK € 40 
CT LTISK & 1. 


Now 
100 


CTLUSKe 0 
PLIATOSK 


QATUSKE 5 I. 


CTLOSK € 10 


This 
CTLOSK 


2 4 | 


you 
io Shs 


wal 


1 3 
read i 


2 3 


Op 2° 
il 


have 
To 


f 3 


2 8 We 


terminates 


records starting with 


written a 
check 


the 


the 


record 
the first 


gecand 
reread 


Neu 


You Can 


imput/foutput operatians, 
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USING THE )RESUME COMMAND 


There might be times when you are using a user-defined function to 
do |/O operations and you want to stop the I/O operation until a later 
time. If you suspend the user-defined function by pressing ATTN once 
(a weak interrupt) and then write the contents of the active workspace 
to the media using the )CONTINUE command, you can use the 
)RESUME command to load the stored workspace into the active 
workspace and reestablish the system as it was. That is, the shared 
variables and suspended function are reestablished in the active 
workspace, and, if you enter > OLC the user-defined function 
continues execution from the point where it was suspended. 


Note: When you use the )JRESUME command, you must make sure 
that the tapes or diskettes are correctly positioned. See the /BM 5770 
APL Reference Manual for a complete description of the JRESUME 
command. 


MORE ABOUT RECORDS AND FILES 


The basic unit of organized data is the record. A record is a collection 
of related data items that are treated as a unit. For example, the 
driver's license most of us carry is a record. A time card is also a 
record. Each record contains items related to the purpose of the 
record. The related items are called fie/ds. The following illustration 
shows a record containing the fields of information that might be 
found on a driver's license: 


License No. Eyes 
t 


Drivers Name Address Date of Birth Heigh Sex 


ROBERT JAMES | 13 FORE AVE. ANYTOWN, N.Y.| 9-30-42 | 132-5711 
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Each field in the previous record contains information relating to a 
specific driver. The length of the field is the maximum number of 
characters that is to be placed in the field. The next illustration shows 
a record containing the fields of information that might be found on a 
time card: 


Name Location Date Serial No. Shift Start Time 


TOM ROBERTS | ENDICOTT | 10-10-74 | 83215 | 2 | 8:00 


A group of records make up a file. Just as a filing cabinet contains a 
number of records in some specific sequence, a 5110 data file also 
contains records in some specific sequence. 


The following illustration shows a record containing customer 
information that would be used in making out an invoice: 


Customer Name Street City, State Billing 
Number Address Code 


Mace, 


137250 | JAMES CONSTRUCTION CO.|13 TOPPER AVE | TROY, N.Y. 


The file would contain as many records as there are customer 
numbers. A file should be given a unique name so that the file can be 
distinguished from other files. Because the record in the previous 
illustration contains customer master information, the file could be 
named CUSTOMER.MASTER. A file containing master information 
about the products in your inventory could be named ITEM.MASTER. 


Different files can contain different record layouts. For example, the 
following illustration shows a record that has items related to the item 
file: 


Item Oty in 
Number Description Price Stock 


874164 WIDGET 
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Organizing a Diskette File 


An important part of any data processing job is fi/e organization. File 
organization is the arrangement of records in a file. 


Sequential Access Files 


Sequential access files are processed consecutively. For example, an 
employee master file contains information needed for various reports 
concerning each employee, such as payroll checks. Because checks 
are usually processed in order by employee number, records are 
processed in order. The lowest employee number is processed first 
and so on until the last record, the highest employee number, is 
processed. 


Sequential processing means records are processed one after another 
in the order they occur in the file. To process only certain records all 
records must be processed, or at least read up to the last record to be 
processed. 
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Direct Access Files 


Since sequential processing can be time consuming, it would be 
helpful if diskette records were available like books in a library. That 
is, you could go to an index, find the location where the book is 
stored, go to the right shelf, and get the book you want. No one 
would read all the books in the shelves before reading the desired 
book. Likewise, it would be desirable to skip the records not needed 
in a job and process only the desired ones. Because direct access 
files allow specified records to be processed by record number, the 
limitation of sequential processing can be overcome by an index. 


To create and use an index, you could use the following procedure: 


1. As you create the direct access, you also create a matrix with 
each row representing a key field in the record. For example, the 
first 7 characters in a record are the item number. As you write 
a record to the file, you also add the item number to a matrix of 
item numbers. . 


2. Now, when you want to directly access a record by record 
number, you can find the record number by using the following 
user-defined function (assuming D1O<0): 


VZ¢LIST INGEX ITEM 
C(LISTA = C7 Lf eLISTIPITEM) I 41.1 teLisTy 
The explicit result of this user-defined function is the row of the 
matrix that contains the specified item number. This explicit 

result also identifies the record number of the specified item 
number in the data file. 


3. Once you find the record number of the specified item number, 


you can directly access and process that record without regard to 
its relation to other records. 
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Ordered and Unordered Records 


The records in a direct access file can be ordered or unordered. An 
ordered file means that the records are arranged in order according to 
some major control field or by frequency of use. An unordered file 
means that the records are not in any particular order. 


With a 5110, it takes /ess time to specify and read 100 records at one 
time than to specify and read individual records 100 times. Therefore, 
arranging your records in order of frequency of use might save you 
processing time. For example, a wholesale distributor organizes the 
file of inventory items by frequency of use. Thus, the most active 
items are at the beginning of the file. Then, when the file is used to 
write customer orders, most of the records are located in a small area 
of the file and can be processed as multiple records. In this example, 
the total time to process the orders is less than if the records were 
scattered throughout the entire file. 


Maintaining Diskette Files 


Once a file is created, fi//e maintenance is often necessary. File 
maintenance means performing those activities that keep a file current 
for daily processing needs. Some file maintenance activities are: 
adding, deleting, and updating records. Adding means putting a 
record in a file after the file is created. Deleting means identifying a 
record so it will not be processed with other records. Updating means 
adding or changing some data in a record. 


Adding Records 


Records can be added at the end of a file after a file has been 
created. Thus, the file is extended by the added records. 


Sometimes, however, the new records must be merged between the 
records already in the file. This might be necessary to keep the file in 
a particular order when the control fields of the new records are not 
higher in sequence than those already in the file; for example, when 
you are using the file for search by key operations. To put the new 
records in the proper sequence, you must use an APL user-defined 
function to sort the file and create a new file containing the added 
records or use the Diskette Sort feature if installed. See the /BM 5770 
Customer Support Functions Reference Manual, SA21-9311, for more 
information on the Diskette Sort feature. 


Tagging Records for Deletion 


When a record becomes inactive, you might not want to process it 
with the other records. A record cannot be physically removed from 
the file during regular processing; therefore, it is necessary to identify 
or tag the record so it can be bypassed. One way to tag such a record 
is to put a code, called a delete code, in a particular location in the 
record. When the file is processed, your user-defined function can 
check for the delete code; if the code is present, the record is 
bypassed. 


When several records in a file have been tagged for deletion, you 
should remove them from the file. This will free diskette space. You 
can remove the deleted records by using a user-defined function to 
copy the records to be retained onto another file or write new records. 
over the deleted records. 


Updating Records 


When you update records in a file, you can add or change some data 
on the record. For example, in an inventory file you might want to 
add the quantity of items received to the previous quantity on hand. 
The record to be updated is read into storage, changed, and written 
back in its original location. 


Designing a Record 


The applications that use a certain file determine what data is needed 
in a record. You should study these applications and then decide the 
/ayout of the record. Layout means the arrangement of fields in a 
record. When you design a record, you must consider processing 
requirements of the record and then determine field length, location, 
and name. 


A name and address file is used to illustrate these design 
considerations. Each record in the file contains the following data: 


Field Size (number of characters) 
Customer Number 8 
Name 20 
Street Address 20 
City and State 20 
Record Code 2 
Delete Code 1 
(Other fields) (total) 47 
Total 116 
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Determining Field Size 


Field size depends on the nature of the data in the field. First, the 
length of the data may vary. In the example, name is 20 characters. 
The length of each customer's name varies, but 20 characters should 
be sufficient for all names. Secondly, all data in a field might be the 
same length. For example, customer number is eight positions, and all 
eight positions are used in each record. 


There are no firm rules for determining field size. The major problem 
involves fields with variable length data. For example, if a name is 
planned as 15 characters, and a new customer has 19 characters in his 
name, a problem arises when you add his record to the file. To avoid 
this problem, try to estimate the largest length of data that will be 
contained in a field. Use this length to determine the field size. 


Providing for a Delete Code 


Remember that records are not automatically deleted. You might want 
to place a delete code in a record, and then when the file is processed 
you must check for the delete code. In the example, if a customer 
becomes inactive, we do not want to process his record. Thus, a 
one-position field is included to provide for a delete code. 


Of course, if you are using an index to find the records in a direct 
access file, you do not need a delete code. Instead, you can remove 
the record key from the index. See Organizing a Diskette File in this 
chapter for information on creating an index. 


Providing Extra Space 


At this stage in planning, it is often wise to allow for data to be added 
to a record. For example, suppose the name and address file was 
created with the fields described, and at a later time each customer's 
zip code is needed. If all positions in the record are used, there is no 
place to add the zip code. Because the record length is not yet 
established, we can allow for such additions to this record. Although it 
is often difficult at the planning stage to imagine what data might be 
added, it is wise to reserve extra space. A minimum of 10% extra 
space is suggested. 


Documenting Record Layout 


When record layouts are documented, your APL user-defined function 
might be easier to write. A record layout should include the order of 
the fields in the record, the length of each field, and the name of each 
field. The following illustration shows the layout of a customer master 
record: 


Customer 
Number 


Street Address 
28 29 


City and State | Other Fields Reserved Space 


1 89 


In the previous example, the sum of the fields is 116 positions. 
However, the record size is 128 positions, thus reserving 12 positions 
for data that might be needed at a later time. 


Determining the. Number of Records in a File 


When determining the number of records in a file, you should consider 
expansion for a reasonable time into the future (at least six months). 
Then when you create the file, if you place dummy records in the file, 
these dummy records ‘can then be replaced with valid records at a 
later time. Of course, you can also add records to the file using an 
ADD operation. 
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Chapter 11. Debugging and Error Recovery Techniques 


SUSPENDED FUNCTION EXECUTION 


The execution of a user-defined function can be interrupted 
(suspended) in a variety of ways: by an error message, by pressing 
the ATTN key, or by using the stop contro! vector (SA). In any case, 
the suspended function is still considered active, since its execution 
can be resumed. Whatever the reason for the suspension, when it 
occurs, the statement number of the next statement to be executed is 
displayed. A branch to the statement number that was displayed or a 
branch to OLC(+OLC) causes normal continuation of the function, and 
a branch out (+0) removes the function. 


When a function is suspended, the 5110 will: 


e Continue to execute system commands except )SAVE, )COPY, and 
)PCOPY. 


e Resume execution of the function at statement n when +n is 
entered. 


e Reopen the definition of any function that is not pendent. A 
pendent function is a function that called the suspended function. If 
a function called a function that called a suspended function, it is 
also pendent (see State /ndicator). 


e Execute other functions or expressions. 
e@ Execute the suspended function again. 
Note: The display of output generated by a previous statement might 
have been interrupted when the suspension occurred. This would be 


caused by the delay between execution of the statement and display 
of the output. 
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STATE INDICATOR 


The state indicator identifies which functions are suspended (*) and at 
what point normal execution can be resumed. Entering )SI causes a 
display of the state indicator. Such a display might have the following 
form: 


SL 
a a 
Gt 


Fed. 


This display indicates that execution was halted just before statement 
7 of function H, that the current use of function H was invoked in 
statement 2 of function G, and that the use of function G was invoked 
in statement 3 of F. The * appearing to the right of H[7] indicates that 
function H is suspended; the functions G and F are said to be 
pendent. 


During the suspension of one function, another function can be 
executed. Thus, if a further suspension occurred in statement 5 of 
function Q, which was invoked in statement 8 of G, a display of the 
state indicator would be as follows: 


SI 
Qos) 
GLB] 

HEV] % 


Gl 


in Na 


An SI DAMAGE error indicates that a suspended function has been 
edited or a pendent function has been erased and the normal 
execution of the suspended function can no longer be resumed. When 
an SI DAMAGE error occurs, the state indicator display will include the 
damaged function name and the statement number ~1. For example, if 
function Q is edited and the modification causes an S| DAMAGE error, 
the display of the state indicator would be as follows: 


oT 
Qo" 1% 
GEG 
Hive 
Gle 


PES 


You can cleat a suspension by entering a branch with no argument 
(that is, +). One suspended function is cleared at a time, along with 
any pendent functions for that suspended function. The first branch 
clears the most recently suspended function, as in the following 
example: 


It is a good practice to clear suspended functions, because suspended 
functions use available storage in the active workspace. Repeated use 
of + clears all the suspended functions; as the functions are cleared, 
they are removed (cleared) from the state indicator. When the state 
indicator is completely cleared, the state indicator display is a blank 
line. 


Note: To display the state indicator with local names, enter the )SINL 
command. 
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Appendix A. 5110 Compatibility with Other APL Systems 


The follwing user-defined functions are example functions that can be 
used to check 5110 user-defined functions for compatibility with other 
APL systems: 


VCHECKEOIV | 
V CHECK FV EA; RLICE; FLIED O10; CPW 
| aCHECK FOR POSSIBLE INCOMPATIBILITES IN FUNCTION F 
21 wE@@ERROR ARRAY CLeCOLUMN LELGENT 
3 aRF=ROW FLAGS CERRORS) RL=ROW LEDGENE 
Lu oI Ni Oe] 
Cd (Puede 
[é] EAePORTABLE CFencr F | 
C7) Re, O 1 Ce CCIPPEA), Le 1+. teEAd, 7° 
REeCV/EAD\ He! 
CERF,’ ',RL,° °,CF 
JOFLe' f° C1+eal 
J EleC2 1 eeCFoe 2 1 3 WCCF), CO.57¢-pCRO TEL 
200 (wa/EDe* ‘9 /DLI ED 


YRPORTABLELT AY 

Vo Ze¢PORTABLE CFECS to ; 
ARETURN A LOGICAL MATRIX CONES AND ZEROS) THE SAME SHAPE as 
ACTOR Foie | TNDICATES CHANGES REQUIRED FOR PORTABILITY 
ACS# LEGAL CHARACTER SET CreCHAkR MATRIX OF F 
ied 
CS¢QAVE CINE), C25+.5H), (86+.719,159,160,1617 
2¢eCR «eS 
Leegv¢ Crs Py) 
Z¢Z2vC'1 [SVO' WHEREIN CF) 
4¢Z2v CFCC WHEREIN CF) 
Zeé2vC'TiAl’ WHEREIN CF) 
Z¢e2vC()TS' WHEREIN CF) 
2¢Z2vC'TT'’ WHEREIN CF 
2¢2v C' TUL WHEREIN CF 
2¢2v0'(]0L' WHEREIN CF: 


mart 

a eee 
ie eee eee oe ee 
ae; a3 5 is 


Bos us 8 
ca ee gee Bee 


; ae 
— Seom* 
t based 


rm 


% 


teh Pt 
eS in re 


Hoe PPE OOD ALOR LE 
, ae 


rm 
Lt i 


VWHERE TNC GY 
Vo 2¢A WHEREIN EB: tito 
Rid alLOCATION OF VECTOR & IN ARRAY RB 
Ce Nie 
LS Le CC OMB) TL ba/COU CRC CLE OR), pA PL pAIOO, CAG sAde 2h 
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VIESTFUNCTIONC OAV 


nad S gece 20 
2 i msvo ‘A’ 


CHECK 'TESTFUNCTION’ 
1 TESTFUNCTION 
18 ec 20 


+ 


t ; 
» £20 1 TSvo peice ee 
These statements might not 


be compatible with another 
APL system. 


JCONTINUE command 69 
)COPY command 46 

)DROP command 76, 88 
JERASE command 138 
)FILEID command 87 

)FNS command 48 

)FREE command 90 

JLOAD command 45 
JMARK command 75, 88 
JOUTSEL command 95 
)PCOPY command 46 
)PROC command 46 
)PROTECT command _ 73, 87 
JRESUME command 45, 146 
JSAVE command 69 

)Sl command 48 

JSINL command 48 
)SYMBOLS command 48 
)VARS command 48 
)VOLID command 73, 85 
JWSID command 48 

OCC system function 62, 95 
DEX system function 138 
OLC system function 155 
OPP system variable 95 
OSVO system function 117 
OSVR system function 138 
>OLC 155 

3 function 95 
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access-protect indicator 82 
active workspace 3, 75 
active workspace control 41 
add data to an existing file 121 
ADD operation 79, 121 
adding records 150 

APL 4 

APL commands 5 

APL expressions 5 

APL internal code 114 

APL internal format 109, 111 
APL shared variable 95, 117 
APL user-defined function 4 
application 5 

arrays 16 

assignment arrow < 13 
atomic vector 115 

audible alarm 64 


beginning of extent (BOE) 84 
BOE 84 
bytes 75 
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catenation 25 DAT shared variable 124 


arrays of unequal sizes 26 data 1 

matrices 25 data cartridge 75 

scalars to arrays 26 data file 

vectors or scalars 25 create 119 

vectors to arrays 26 direct access 108 
center character string in matrix row 35 formats 109 
changing workspace environment 43 ' sequential access 108 
character constants 15 data files 75 
character position 134 data processing 2 
clear suspended functions 157 data representation 14 
CLEAR WS environment 42 data security 73 
complex name 87 data types 50 

' compress data 79 data written to the data file 120 

console contro! 65, 97, 101 debugging 155 
console storage 59 degree of coupling 117 
CONTINUE 69 delete code 151 
controlling display screen 63 delete comment lines from a function 
controlling files 72 delete duplicate elements 33 
convert to a matrix 105 delete function names 34 
COPY 46 delete leading blanks 38 
count unique characters in vector 35 delete name from list 39 
create a data file 119 deleted records 151 
create a matrix from a vector 31 deleting records 150 
creating lists 27 designing a record 151 
CTL DOMAIN ERROR_ 132 determining field size 152 
CTL shared variable 124 _ determining size of file 68 
cursor return character 110 direct access data file 108, 119 


diskette 3, 6, 81 
diskette addressing 83 
diskette drive 81 
diskette files 
organizing 148 
maintenance 150 
diskette formats 85 
diskette initialization 81, 86 
diskette sort feature 150 
diskette storage 54 
diskette volume ID 82 
display screen 4, 7, 63 
read from 133 
write to 133 
documenting record layout 153 
DROP 76, 88 
drop blanks 102 
drop blanks and periods 102 
drop extra blanks 105 
drop leading blanks 102 
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EBCDIC code 114 

empty arrays 21 

end of block character 110 
end of data (EOD) 84 

end of extent (EOE) 84 


EOD 34, 84 
EOE 84, 102 
ERASE 138 


error recovery 155 
establishing an APL shared variable 117 


fields 146 

file headers 75 

file ID 87 

file maintenance 
adding records 150 
deleting records 151 
updating records 151 

file organization 146 

FILEID 87 

find first nonblank character 33 

find index of name 103 

find location of name in list 39 


FNS 48 

format 6 

format 
APL internal 109, 111 
function 95 
general exchange 109, 111 
mixed 113 


nontranslated 114 

unblocked and unspanned 112 
formatting reports 98, 101 
formatting tape 75 
FREE 90 


general exchange format 109, 111 
generate a matrix 18 
generating arrays 17 
getting information from a file 71 


hard copy output 4 

helpful functions 102 
convert to a matrix 105 
drop blanks 102 
drop blanks and period 102 
drop extra blanks 105 
drop leading blanks 102 
find index of name 103 
insert blank lines 104 
join two variables 106 
left-justify 103 
print a matrix 104 
replace periods 102 


1/O processor 116 

IN operation 122 

index cylinder 84 

index file 149 

index track 90 

indexing arrays 22 
initialization, diskette 81, 86 
input 2 

input/output operations 118 
INR operation 132 

insert blank lines 104 
interface 12 

INTERFACE QUOTA EXHAUSTED 117 
internal precision 96 

internal storage 3 

IOR operation 125 

IORH operation 125 


join two variables 106 
join vectors and print results 38 
joining arrays 25 


key value 131 
keyboard 3, 7, 60 
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laminated records 127 operations 


lamination 28 ADD 79, 121 

language elements 13 INR 132 

left justify 103 OR 125 

left-justify character string in matrix 36 — IORH 125 

library control 67 OUT 78 

list each function in workspace 36 OUTF 119 

list each variable in workspace 37 PRT 137 

LOAD 45 % operations to be performed 118 
logical data 15 ordered file 150 

logical record 108 ordered records 150 
lowercase characters 60 organizing a diskette file 148 


OUT operation 78, 119 
OUTF operation 119 


output 2 

output format 95 

OUTSEL 95 
maintaining diskette files 150 
make scalar or vector into a matrix 34 
MARK 75, 88 
MAT PUT statement 109 
matrices 16 
merge two variables 33 pair of shared variables 124 
mixed format 113 PCOPY 46 


pendent function 155 
perform operation on conditions 40 
physical record 108 


precision 

internal 96 
negative sign 14 printed 96 
nontranslated format 114 print data 137 
number of records 126 printer 3 
number of records in the file 153 printing data 95 
numbers 14 PROC 46 
numeric precision 14 procedure file 46 
numeric value range 14 process 2, 8 


program 1, 12 

PROTECT 73, 87 
providing extra space 152 
PRT operation 137 

PUT statement 109 


quotes 15 
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random access 77 
rank of an array 19 
read a data file 122 
read direct 108, 119 
read from the display screen 133 
read multiple records 127 
read records 126 
read sequentially 122 
read/write head 82 
read-only a data file 132 
record 146 
records 
laminated 127 
ordered 150 
unordered 150 
updating 124 
designing 151 
fields 146 
layout 151 
logical 108 
numbering 126 
physcial 108 
remove alpha characters from vector 32 
remove duplicate blanks from a vector 31 
replace periods 102 
replace trailing blanks 32 
report formatting 98, 101 
reshape function 17 
' RESUME 45, 146 
resume execution 155 
retracting the shared variable 138 
return code 120, 123 
return even numbered elements 32 
right-justify character string in matrix 35 


SA 155 

SAFE switch 73 

sample input/output operations 140 
SAVE 69 

scalars 16 

scaled representation 14 

scientific notation 14 

search by key 126, 131 

search file for a specific record 131 
sector 84 

security 73 

sequential access 77 

sequential access data file 108, 119 
sequentially read 122 
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